ecosemantic-core 0.1.8__tar.gz

ecosemantic_core-0.1.8/.gitignore

@@ -0,0 +1,24 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+node_modules/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.json
+htmlcov/
+
+.env
+.env.*
+!.env.example
+
+.DS_Store
+graphify-out
+knowledge/
+.okf-cache.json
+**/ecosemantic/view/static/

ecosemantic_core-0.1.8/LICENSE

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

ecosemantic_core-0.1.8/NOTICE

@@ -0,0 +1,13 @@
+EcoSemantic
+Required Notice: Copyright 2026 Carlos Gaete-Morales (https://github.com/cdgaete/ecosemantic)
+
+EcoSemantic is licensed under the PolyForm Noncommercial License 1.0.0, in LICENSE
+and at https://polyformproject.org/licenses/noncommercial/1.0.0. Any noncommercial
+purpose is permitted. Commercial use needs a separate licence from Carlos
+Gaete-Morales: cdgaete@gmail.com.
+
+The page that ecosemantic-view carries bundles third-party software under its
+own licences; their notices are in ecosemantic/view/static/THIRD_PARTY_NOTICES.txt
+inside that distribution. Components of the page adapt shadcn/ui, Copyright (c)
+2023 shadcn, under the MIT licence, as page/PROVENANCE.md in the source
+repository records.

ecosemantic_core-0.1.8/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: ecosemantic-core
+Version: 0.1.8
+Summary: The EcoSemantic ports, pure computations, portable format and filesystem storage.
+Project-URL: Homepage, https://github.com/cdgaete/ecosemantic
+Project-URL: Repository, https://github.com/cdgaete/ecosemantic
+Project-URL: Issues, https://github.com/cdgaete/ecosemantic/issues
+Project-URL: Changelog, https://github.com/cdgaete/ecosemantic/blob/main/CHANGELOG.md
+Author-email: Carlos Gaete-Morales <cdgaete@gmail.com>
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: JSON-LD,LCA,life cycle assessment,openLCA,product system
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: asteval<2,>=1.0.10
+Requires-Dist: duckdb<2,>=1.5
+Requires-Dist: ecosemantic-engine==0.1.8
+Requires-Dist: filelock<4,>=3.29.5
+Requires-Dist: numpy>=2.5
+Requires-Dist: olca-schema==2.4.0
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6.0.1
+Requires-Dist: scipy>=1.16
+Requires-Dist: watchfiles<2,>=1.0
+Description-Content-Type: text/markdown
+
+# ecosemantic-core
+
+The ports of EcoSemantic and the types they carry, the pure computations over a product system, the portable package a model travels in, the tables folder, the event bus, the drawing the page renders, and the two backends that serve the ports from installed database bundles and from a folder of product systems.
+
+## Names it publishes
+
+- `ecosemantic.ports` — the protocols every backend answers and the types they carry: `activity`, `calculation`, `graph`, `install`, `inventory`, `resolver`, `run`, `search`, `storage` and `types`.
+- `ecosemantic.compute` — the pure computations, with no store behind them: `parameters`, `overrides`, `links`, `consequences`, `edits`, `results`, `render`, `montecarlo` and `accounts`.
+- `ecosemantic.package` — the portable package a product system travels in, openLCA's JSON-LD among its forms, with the change log, the manifest, the gates and the compilation that reads it.
+- `ecosemantic.tables` — a product system as a folder of text: a YAML model, CSV inputs and CSV results.
+- `ecosemantic.events` — one bus per server process, fed by the storage every write goes through and by the watcher of each run.
+- `ecosemantic.geometry`, `layout`, `routes`, `textmap` and `troubles` — the drawing, in the pixels the page renders it at: each card's rows, where a process sits, every arrow as an orthogonal route, the drawing as characters an agent reads, and what is wrong with it.
+- `ecosemantic.quantity` and `scaling` — a quantity as the canvas writes it, and each card's exchanges scaled to one unit of the functional unit.
+- `ecosemantic.backends.filesystem` — product systems, runs, installs and their records in a folder, and the watcher that announces what changes.
+- `ecosemantic.backends.native` — the databases installed under one data directory: their registry entries, their catalogs and their compiled backgrounds, serving the search, inventory and calculation ports.
+
+## What it depends on
+
+`ecosemantic-engine` at the same version, and pydantic, olca-schema, asteval, duckdb, numpy, scipy, filelock, watchfiles and pyyaml.
+
+## Installing it
+
+`pip install ecosemantic` installs this distribution with the other five and the `ecosemantic` command. `pip install ecosemantic-core` installs it alone, for a backend or a tool that depends on the ports rather than on the server.
+
+## Licence
+
+PolyForm Noncommercial License 1.0.0, copyright Carlos Gaete-Morales: `LICENSE` and `NOTICE` in this distribution. Any noncommercial purpose is permitted, by individuals and by charities, schools, public research and government bodies; commercial use needs a separate licence from him (cdgaete@gmail.com). EcoSemantic is his trademark, and the licence grants no right to use that name (`TRADEMARK.md` in the repository). The code is published from https://github.com/cdgaete/ecosemantic.

ecosemantic_core-0.1.8/README.md

@@ -0,0 +1,27 @@
+# ecosemantic-core
+
+The ports of EcoSemantic and the types they carry, the pure computations over a product system, the portable package a model travels in, the tables folder, the event bus, the drawing the page renders, and the two backends that serve the ports from installed database bundles and from a folder of product systems.
+
+## Names it publishes
+
+- `ecosemantic.ports` — the protocols every backend answers and the types they carry: `activity`, `calculation`, `graph`, `install`, `inventory`, `resolver`, `run`, `search`, `storage` and `types`.
+- `ecosemantic.compute` — the pure computations, with no store behind them: `parameters`, `overrides`, `links`, `consequences`, `edits`, `results`, `render`, `montecarlo` and `accounts`.
+- `ecosemantic.package` — the portable package a product system travels in, openLCA's JSON-LD among its forms, with the change log, the manifest, the gates and the compilation that reads it.
+- `ecosemantic.tables` — a product system as a folder of text: a YAML model, CSV inputs and CSV results.
+- `ecosemantic.events` — one bus per server process, fed by the storage every write goes through and by the watcher of each run.
+- `ecosemantic.geometry`, `layout`, `routes`, `textmap` and `troubles` — the drawing, in the pixels the page renders it at: each card's rows, where a process sits, every arrow as an orthogonal route, the drawing as characters an agent reads, and what is wrong with it.
+- `ecosemantic.quantity` and `scaling` — a quantity as the canvas writes it, and each card's exchanges scaled to one unit of the functional unit.
+- `ecosemantic.backends.filesystem` — product systems, runs, installs and their records in a folder, and the watcher that announces what changes.
+- `ecosemantic.backends.native` — the databases installed under one data directory: their registry entries, their catalogs and their compiled backgrounds, serving the search, inventory and calculation ports.
+
+## What it depends on
+
+`ecosemantic-engine` at the same version, and pydantic, olca-schema, asteval, duckdb, numpy, scipy, filelock, watchfiles and pyyaml.
+
+## Installing it
+
+`pip install ecosemantic` installs this distribution with the other five and the `ecosemantic` command. `pip install ecosemantic-core` installs it alone, for a backend or a tool that depends on the ports rather than on the server.
+
+## Licence
+
+PolyForm Noncommercial License 1.0.0, copyright Carlos Gaete-Morales: `LICENSE` and `NOTICE` in this distribution. Any noncommercial purpose is permitted, by individuals and by charities, schools, public research and government bodies; commercial use needs a separate licence from him (cdgaete@gmail.com). EcoSemantic is his trademark, and the licence grants no right to use that name (`TRADEMARK.md` in the repository). The code is published from https://github.com/cdgaete/ecosemantic.

ecosemantic_core-0.1.8/ecosemantic/backends/filesystem/activity.py

@@ -0,0 +1,103 @@
+"""The activity port over a directory: one JSON Lines file per agent under the systems
+directory."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+from filelock import FileLock
+from pydantic import ValidationError
+
+from ecosemantic.errors import NotFound, Unavailable
+from ecosemantic.ports.types import (
+    AgentSummary,
+    Call,
+    CallDraft,
+    agents_of,
+    checked_agent,
+    selected,
+)
+
+ACTIVITY_DIR = "activity"
+SUFFIX = ".jsonl"
+
+
+class FilesystemActivity:
+    """Recorded calls as one line each, appended to the file of the agent that made them.
+
+    Two processes over one directory may serve agents of one name, so a file is appended to and
+    read under a lock both take.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def _folder(self) -> Path:
+        return self.root / ACTIVITY_DIR
+
+    def _lock(self, agent: str) -> FileLock:
+        return FileLock(self._folder() / f"{agent}.lock")
+
+    def _append(self, call: Call) -> Call:
+        self._folder().mkdir(parents=True, exist_ok=True)
+        with self._lock(call.agent):
+            with (self._folder() / f"{call.agent}{SUFFIX}").open("a", encoding="utf-8") as handle:
+                handle.write(call.model_dump_json() + "\n")
+        return call
+
+    def _read(self, agent: str | None) -> list[Call]:
+        if not self._folder().is_dir():
+            return []
+        if agent is not None:
+            files = [self._folder() / f"{checked_agent(agent)}{SUFFIX}"]
+        else:
+            files = sorted(self._folder().glob(f"*{SUFFIX}"))
+        calls: list[Call] = []
+        for file in files:
+            if file.is_file():
+                with self._lock(file.name.removesuffix(SUFFIX)):
+                    calls.extend(_parsed(file))
+        return calls
+
+    async def record(self, draft: CallDraft) -> Call:
+        call = Call(id=uuid.uuid4(), **draft.model_dump())
+        return await asyncio.to_thread(self._append, call)
+
+    async def list_calls(
+        self,
+        agent: str | None = None,
+        product_system_id: uuid.UUID | None = None,
+        after: datetime | None = None,
+    ) -> list[Call]:
+        calls = await asyncio.to_thread(self._read, agent)
+        return selected(calls, agent, product_system_id, after)
+
+    async def get_call(self, call_id: uuid.UUID) -> Call:
+        for call in await asyncio.to_thread(self._read, None):
+            if call.id == call_id:
+                return call
+        raise NotFound(f"no call {call_id}")
+
+    async def list_agents(self) -> list[AgentSummary]:
+        return agents_of(await asyncio.to_thread(self._read, None))
+
+
+def _parsed(file: Path) -> list[Call]:
+    """A file's calls, or Unavailable naming the file, the line and the first field this version
+    cannot read in it."""
+    calls: list[Call] = []
+    for number, line in enumerate(file.read_text(encoding="utf-8").splitlines(), start=1):
+        try:
+            calls.append(Call.model_validate_json(line))
+        except ValidationError as error:
+            first = error.errors(include_url=False)[0]
+            field = ".".join(str(part) for part in first["loc"])
+            raise Unavailable(
+                f"{file.name} line {number} cannot be read by this version: "
+                f"{field}: {first['msg']}",
+                hint=f"remove {file} to read the activity again",
+            ) from error
+    return calls

ecosemantic_core-0.1.8/ecosemantic/backends/filesystem/installs.py

@@ -0,0 +1,81 @@
+"""The install port over a directory: one folder per install under the data directory."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import AsyncIterator
+from datetime import datetime
+from pathlib import Path
+
+from filelock import AsyncFileLock
+
+from ecosemantic.backends.filesystem.records import RecordFolder, newest_first
+from ecosemantic.ports.types import Install, InstallDraft, InstallPatch
+
+INSTALLS_DIR = "installs"
+INSTALL_FILE = "install.json"
+UPLOADS_DIR = "uploads"
+
+
+def install_dir(root: Path, install_id: uuid.UUID) -> Path:
+    """The directory of one install under the data directory, whether or not it exists yet."""
+    return root / INSTALLS_DIR / str(install_id)
+
+
+def uploads_dir(root: Path) -> Path:
+    """The directory a package uploaded for an install is written to before that install reads
+    it."""
+    return root / INSTALLS_DIR / UPLOADS_DIR
+
+
+class FilesystemInstalls:
+    """Install records as one JSON file per install, newest first by the time they were posted.
+
+    The install process writes a record from its own process while the server reads it, so a
+    record is replaced whole and every change is read and written under a lock both take.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self.records = RecordFolder(root, INSTALLS_DIR, INSTALL_FILE, Install, "install")
+
+    def read_record(self, install_id: uuid.UUID) -> Install:
+        """One install, read synchronously; the install process's callback runs off the event
+        loop."""
+        return self.records.read(install_id)
+
+    def apply_patch(self, install_id: uuid.UUID, patch: InstallPatch) -> Install:
+        """The record with the patch's named fields applied, written synchronously."""
+        return self.records.patch(install_id, patch.applied_to)
+
+    async def post_install(self, draft: InstallDraft) -> Install:
+        def construct(posted_at: datetime) -> Install:
+            return Install(id=uuid.uuid4(), draft=draft, posted_at=posted_at)
+
+        return await asyncio.to_thread(self.records.post, construct)
+
+    async def get_install(self, install_id: uuid.UUID) -> Install:
+        return await asyncio.to_thread(self.read_record, install_id)
+
+    async def list_installs(self) -> list[Install]:
+        return newest_first(await asyncio.to_thread(self.records.all))
+
+    async def cancel_install(self, install_id: uuid.UUID) -> Install:
+        def ask() -> Install:
+            return self.records.patch(
+                install_id, lambda install: install.cancellation().applied_to(install)
+            )
+
+        return await asyncio.to_thread(ask)
+
+    async def update_install(self, install_id: uuid.UUID, patch: InstallPatch) -> Install:
+        return await asyncio.to_thread(self.apply_patch, install_id, patch)
+
+    def slot(self) -> AsyncFileLock:
+        """The workspace's one-install slot, which every process over this directory shares."""
+        return self.records.slot()
+
+    def changes(self) -> AsyncIterator[uuid.UUID]:
+        """Every install any process wrote, from the moment this is called."""
+        return self.records.changed()

ecosemantic_core-0.1.8/ecosemantic/backends/filesystem/records.py

@@ -0,0 +1,183 @@
+"""A record folder: one directory per record under its kind's directory, the record replaced
+whole under a lock both processes take."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Iterable
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Protocol, cast
+
+from filelock import AsyncFileLock, FileLock
+from pydantic import BaseModel, ValidationError
+
+from ecosemantic.backends.filesystem.watching import touched
+from ecosemantic.backends.retry import read_bytes, replace
+from ecosemantic.errors import NotFound, Unavailable
+
+SLOT_FILE = "slot.lock"
+POST_LOCK = "post.lock"
+
+
+class Posted(Protocol):
+    """What a record carries for a listing: its id, and the time it was posted."""
+
+    id: uuid.UUID
+    posted_at: datetime
+
+
+def newest_first[T: Posted](records: Iterable[T]) -> list[T]:
+    """Records newest first, the id breaking a tie between two posted at once."""
+    return sorted(records, key=lambda record: (record.posted_at, str(record.id)), reverse=True)
+
+
+def now() -> datetime:
+    """The current instant in UTC, the clock a record's posted time is measured from."""
+    return datetime.now(UTC)
+
+
+def next_posted_at(now: datetime, newest: datetime | None) -> datetime:
+    """A new record's posted time, newest-first independent of the clock's resolution: the
+    clock, or one microsecond past the store's newest when the clock would tie two."""
+    if newest is None:
+        return now
+    return max(now, newest + timedelta(microseconds=1))
+
+
+class RecordFolder[T: BaseModel]:
+    """The records of one kind, as one JSON file per record in a folder of its own.
+
+    A record is written from another process while this one reads it, so it is replaced whole,
+    never rewritten in place, and every change is read and written under a lock both take.
+    """
+
+    def __init__(self, root: Path, kind: str, record_file: str, model: type[T], noun: str) -> None:
+        self.root = root
+        self.kind = kind
+        self.record_file = record_file
+        self.model = model
+        self.noun = noun
+
+    def folder(self, record_id: uuid.UUID) -> Path:
+        """The directory of one record under its kind's directory, whether or not it exists."""
+        return self.root / self.kind / str(record_id)
+
+    def lock(self, record_id: uuid.UUID) -> FileLock:
+        """The record's file lock, taken by every read-and-write of it, from either process."""
+        folder = self.root / self.kind
+        folder.mkdir(parents=True, exist_ok=True)
+        return FileLock(folder / f"{record_id}.lock")
+
+    def post_lock(self) -> FileLock:
+        """The lock every poster of this kind takes, so two cannot mint the same posted time."""
+        folder = self.root / self.kind
+        folder.mkdir(parents=True, exist_ok=True)
+        return FileLock(folder / POST_LOCK)
+
+    def read(self, record_id: uuid.UUID) -> T:
+        """One record, or NotFound when no folder holds it."""
+        record = self.folder(record_id) / self.record_file
+        if not record.is_file():
+            raise NotFound(f"no {self.noun} {record_id}")
+        return self._parsed(record)
+
+    def write(self, record_id: uuid.UUID, record: T) -> T:
+        """The record written, staged beside its file and moved over it within the bounded
+        retry, so a reader sees the whole of one version or the whole of the other."""
+        folder = self.folder(record_id)
+        folder.mkdir(parents=True, exist_ok=True)
+        staged = folder / f"{self.record_file}.tmp"
+        staged.write_bytes(record.model_dump_json(indent=1).encode("utf-8"))
+        replace(staged, folder / self.record_file)
+        return record
+
+    def patch(self, record_id: uuid.UUID, change: Callable[[T], T]) -> T:
+        """The record with the change applied, read and written under its lock."""
+        with self.lock(record_id):
+            return self.write(record_id, change(self.read(record_id)))
+
+    def post(self, construct: Callable[[datetime], T]) -> T:
+        """A new record posted under the kind's lock, its posted time advanced past the newest
+        stored so two posters cannot mint the same instant."""
+        with self.post_lock():
+            record = construct(self._next_posted_at())
+            return self.write(cast(Posted, record).id, record)
+
+    def _next_posted_at(self) -> datetime:
+        """The posted time of the next record of this kind: the clock, advanced past the newest."""
+        newest = max(
+            (record.posted_at for record in cast(Iterable[Posted], self.all())), default=None
+        )
+        return next_posted_at(now(), newest)
+
+    def all(self) -> list[T]:
+        """Every record of this kind."""
+        folder = self.root / self.kind
+        if not folder.is_dir():
+            return []
+        return [
+            self._parsed(path / self.record_file)
+            for path in folder.iterdir()
+            if (path / self.record_file).is_file()
+        ]
+
+    def changed(self) -> AsyncGenerator[uuid.UUID]:
+        """Every record any process wrote under this kind's directory, from the moment this is
+        called: the watch is armed eagerly, so a write between this call and the first read is
+        announced."""
+        queue: asyncio.Queue[uuid.UUID] = asyncio.Queue()
+        watching = asyncio.create_task(self._watch(touched(self.root / self.kind), queue))
+
+        async def iterate() -> AsyncGenerator[uuid.UUID]:
+            try:
+                while True:
+                    yield await queue.get()
+            finally:
+                watching.cancel()
+
+        return iterate()
+
+    async def _watch(
+        self, batches: AsyncIterator[set[Path]], queue: asyncio.Queue[uuid.UUID]
+    ) -> None:
+        async for batch in batches:
+            found = {record for path in batch if (record := self._record_of(path)) is not None}
+            for record_id in sorted(found, key=str):
+                if (self.folder(record_id) / self.record_file).is_file():
+                    queue.put_nowait(record_id)
+
+    def _record_of(self, path: Path) -> uuid.UUID | None:
+        """The record a written path belongs to, or none for a path that names no record."""
+        folder = self.root / self.kind
+        try:
+            first = path.resolve().relative_to(folder.resolve()).parts[0]
+        except (ValueError, IndexError):
+            return None
+        try:
+            return uuid.UUID(first)
+        except ValueError:
+            return None
+
+    def slot(self) -> AsyncFileLock:
+        """The single slot every process over this directory takes, released when its holder's
+        process ends. Each try is non-blocking on the event loop, so a caller cancelled while it
+        waits holds nothing."""
+        folder = self.root / self.kind
+        folder.mkdir(parents=True, exist_ok=True)
+        return AsyncFileLock(folder / SLOT_FILE, run_in_executor=False)
+
+    def _parsed(self, record: Path) -> T:
+        """The record parsed, or Unavailable naming it and the first field this version cannot
+        read in it."""
+        try:
+            return self.model.model_validate_json(read_bytes(record))
+        except ValidationError as error:
+            first = error.errors(include_url=False)[0]
+            field = ".".join(str(part) for part in first["loc"])
+            raise Unavailable(
+                f"{self.noun} {record.parent.name} cannot be read by this version: "
+                f"{field}: {first['msg']}",
+                hint=f"remove {record.parent} to list and start {self.noun}s again",
+            ) from error

ecosemantic_core-0.1.8/ecosemantic/backends/filesystem/run_folder.py

@@ -0,0 +1,55 @@
+"""Where a run lives on disk: one directory per run under the systems directory, and the
+heartbeat its worker beats there."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from threading import Event, Thread
+
+RUNS_DIR = "runs"
+RECORD_FILE = "run.json"
+LOG_FILE = "worker.log"
+HEARTBEAT_FILE = "heartbeat"
+
+
+def run_dir(root: Path, run_id: uuid.UUID) -> Path:
+    """The directory of one run under a systems directory, whether or not it exists yet."""
+    return root / RUNS_DIR / str(run_id)
+
+
+def beat(folder: Path) -> None:
+    """Mark the worker carrying the run in this folder as alive now, by the heartbeat file's
+    modification time."""
+    (folder / HEARTBEAT_FILE).touch()
+
+
+def heartbeat_age(folder: Path) -> float | None:
+    """Seconds since the worker carrying the run in this folder last beat, or None when it never
+    has."""
+    heartbeat = folder / HEARTBEAT_FILE
+    if not heartbeat.is_file():
+        return None
+    return time.time() - heartbeat.stat().st_mtime
+
+
+@contextmanager
+def beating(folder: Path, every: float) -> Iterator[None]:
+    """Beat this folder's heartbeat every `every` seconds until the block ends, so a step that
+    reports nothing does not look like a process that is gone."""
+    stop = Event()
+
+    def keep_beating() -> None:
+        while not stop.wait(every):
+            beat(folder)
+
+    beater = Thread(target=keep_beating, daemon=True)
+    beater.start()
+    try:
+        yield
+    finally:
+        stop.set()
+        beater.join()