polyweave-gamekit 0.1.0__tar.gz

polyweave_gamekit-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.roadkeep
+
+# the plugin's working state, which `[paths] work` names and nothing outside the tree;
+# tools/gate.py keeps its log and stamp under it too
+.polyweave/
+# What tools\gate-vm.cmd brings back from the VMware guest.
+TestResults/
+
+# a run redirected to a file at the root is evidence, not source, and the commit tool
+# stages the whole tree
+/*.log
+
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/

polyweave_gamekit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Oliveira
+
+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.

polyweave_gamekit-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: polyweave-gamekit
+Version: 0.1.0
+Summary: Make a game's parts by declaring what each must satisfy: 3D assets, pictures, sound loops and the world's text, on top of Blender, Godot and paid generators.
+Project-URL: Homepage, https://alegauss.github.io/polyweave/
+Project-URL: Source, https://github.com/alegauss/polyweave
+Project-URL: Issues, https://github.com/alegauss/polyweave/issues
+Author: Alexandre Oliveira
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 3d,assets,blender,claude-code,gamedev,godot,mcp,sound
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=10
+Provides-Extra: audio
+Requires-Dist: pedalboard>=0.9; extra == 'audio'
+Provides-Extra: blender
+Requires-Dist: bpy>=4.2; extra == 'blender'
+Provides-Extra: dev
+Requires-Dist: pytest-xdist>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: stems
+Requires-Dist: demucs>=4; extra == 'stems'
+Provides-Extra: text
+Requires-Dist: fonttools>=4.40; extra == 'text'
+Description-Content-Type: text/markdown
+
+# polyweave
+
+A Claude Code plugin for making a game's parts by declaring what each has to satisfy:
+3D assets (geometry, surface and motion) and the pictures they start from, sound loops
+held to a seam, and the names and lines of the game's world. It works on top of Blender,
+Godot and paid generators. Levels are next, on the roadmap.
+
+The premise: generating a mesh is the cheap part. The expensive part is everything between
+*having a mesh* and *knowing it is right*, and today that is a person changing one number at
+a time and looking at a two-minute render. polyweave aims to close that loop — you state
+what the asset has to satisfy, and it searches for the parameters that satisfy it, measuring
+against the reference rather than against an opinion.
+
+It is built for an agent to drive. No GUI, no account, no hosted service: it runs on your
+machine against files in your own repository.
+
+## Status
+
+The status is not typed here, because a typed status goes stale: this file said "Block A
+has started" a hundred shipped lines after most blocks were built. `docs/ROADMAP.md` holds
+what is still open, block by block, and `docs/CHANGELOG.md` what has shipped; the site's
+landing page states the count, derived from the roadmap. Every line in that file was drawn
+from a failure measured in a real project, and it also carries the non-goals, which say
+what this deliberately will not be.
+
+No number anywhere is yet a measurement of polyweave: that is Block H, where a real game
+adopts the plugin and the loop ledger records what an asset cost to make each way.
+
+## The plugin
+
+Python, under `src/polyweave`, against Python 3.11 — which is the interpreter Blender 4.2
+ships, and code here may have to run inside it. It depends on numpy and Pillow, and on
+nothing else. Blender is optional: `pip install -e ".[blender]"` brings `bpy` in for the
+render path, and without it `capabilities()` says so and a render refuses rather than
+importing a renderer nobody asked for.
+
+On PyPI the distribution is **`polyweave-gamekit`**, because `polyweave` there is an
+unrelated project: `pip install polyweave-gamekit[audio]` installs it with an extra, and
+the import and `python -m polyweave` keep the short name. A `v<version>` tag publishes it
+through `.github/workflows/publish.yml`, to TestPyPI first and then PyPI, and a manual run
+of that workflow rehearses on TestPyPI alone; the version is `polyweave.__version__`, and the
+plugin manifest carries the same number.
+
+It is served as a Claude Code plugin from this repository. `.claude-plugin/` holds the
+marketplace, which names `plugin/` as the plugin: its manifest, its hooks and
+`skills/polyweave/`, the skill that drives it, and nothing else an adopter would have to
+download. `python -m polyweave serve` is the MCP server every operation is exposed
+through.
+
+```
+python tools/gate.py     # the suite, in tests/, under a lock, stamped
+python -m ruff check .   # the linter
+python -m ruff format .  # the formatter
+```
+
+## Roadmap docs
+
+`docs/ROADMAP.md`, `docs/CHANGELOG.md` and `docs/IMPROVEMENTS.md` are maintained by roadkeep
+and are not edited by hand — `python .roadkeep/scripts/roadkeep.py` is the entry point here.
+
+`docs/specs/` is the other half: the contracts that more than one roadmap line depends on — a
+file format, a vocabulary, a behaviour every call obeys. Those are ordinary documents, edited
+directly, and they are settled enough to build against.
+
+## The site
+
+`site/` is the public page, at `alegauss.github.io/polyweave/` once Pages is pointed at the
+`site` workflow. It says on the page — second, above everything but the hero — how many
+blocks are built and how many lines are still open.
+
+Everything it counts is generated from `docs/ROADMAP.md` through roadkeep rather than typed,
+so the page cannot disagree with the file, and `npm test` fails the build if the stated
+status differs from the roadmap's. See [`site/README.md`](site/README.md).
+
+## More tools by alegauss
+
+For Claude Code:
+
+- **[Claude Code Tray](https://alegauss.github.io/claude-tray/)**: your rate-limit usage as a Windows tray icon that turns red before you run out.
+- **[roadkeep](https://alegauss.github.io/roadkeep/)**: keeps ROADMAP, CHANGELOG and IMPROVEMENTS to one format, as a CLI and a Claude Code plugin.
+- **[commitclerk](https://alegauss.github.io/commitclerk/)**: Conventional Commits messages from your staged diff, in a single-file Python CLI.
+
+For Windows developers:
+
+- **[winwright](https://alegauss.github.io/winwright/)**: drives a Windows desktop app from a test and reports what was actually observed.
+- **[FreeWilly](https://alegauss.github.io/freewilly/)**: Docker on Windows without Docker Desktop, with no admin prompt and no telemetry.
+- **[Quickshell](https://alegauss.github.io/quickshell/)**: an SSH client for Windows with sessions, keys, SFTP and tunnels, and without the rest of the suite.
+
+All of them: [alegauss.github.io](https://alegauss.github.io/)

polyweave_gamekit-0.1.0/README.md

@@ -0,0 +1,89 @@
+# polyweave
+
+A Claude Code plugin for making a game's parts by declaring what each has to satisfy:
+3D assets (geometry, surface and motion) and the pictures they start from, sound loops
+held to a seam, and the names and lines of the game's world. It works on top of Blender,
+Godot and paid generators. Levels are next, on the roadmap.
+
+The premise: generating a mesh is the cheap part. The expensive part is everything between
+*having a mesh* and *knowing it is right*, and today that is a person changing one number at
+a time and looking at a two-minute render. polyweave aims to close that loop — you state
+what the asset has to satisfy, and it searches for the parameters that satisfy it, measuring
+against the reference rather than against an opinion.
+
+It is built for an agent to drive. No GUI, no account, no hosted service: it runs on your
+machine against files in your own repository.
+
+## Status
+
+The status is not typed here, because a typed status goes stale: this file said "Block A
+has started" a hundred shipped lines after most blocks were built. `docs/ROADMAP.md` holds
+what is still open, block by block, and `docs/CHANGELOG.md` what has shipped; the site's
+landing page states the count, derived from the roadmap. Every line in that file was drawn
+from a failure measured in a real project, and it also carries the non-goals, which say
+what this deliberately will not be.
+
+No number anywhere is yet a measurement of polyweave: that is Block H, where a real game
+adopts the plugin and the loop ledger records what an asset cost to make each way.
+
+## The plugin
+
+Python, under `src/polyweave`, against Python 3.11 — which is the interpreter Blender 4.2
+ships, and code here may have to run inside it. It depends on numpy and Pillow, and on
+nothing else. Blender is optional: `pip install -e ".[blender]"` brings `bpy` in for the
+render path, and without it `capabilities()` says so and a render refuses rather than
+importing a renderer nobody asked for.
+
+On PyPI the distribution is **`polyweave-gamekit`**, because `polyweave` there is an
+unrelated project: `pip install polyweave-gamekit[audio]` installs it with an extra, and
+the import and `python -m polyweave` keep the short name. A `v<version>` tag publishes it
+through `.github/workflows/publish.yml`, to TestPyPI first and then PyPI, and a manual run
+of that workflow rehearses on TestPyPI alone; the version is `polyweave.__version__`, and the
+plugin manifest carries the same number.
+
+It is served as a Claude Code plugin from this repository. `.claude-plugin/` holds the
+marketplace, which names `plugin/` as the plugin: its manifest, its hooks and
+`skills/polyweave/`, the skill that drives it, and nothing else an adopter would have to
+download. `python -m polyweave serve` is the MCP server every operation is exposed
+through.
+
+```
+python tools/gate.py     # the suite, in tests/, under a lock, stamped
+python -m ruff check .   # the linter
+python -m ruff format .  # the formatter
+```
+
+## Roadmap docs
+
+`docs/ROADMAP.md`, `docs/CHANGELOG.md` and `docs/IMPROVEMENTS.md` are maintained by roadkeep
+and are not edited by hand — `python .roadkeep/scripts/roadkeep.py` is the entry point here.
+
+`docs/specs/` is the other half: the contracts that more than one roadmap line depends on — a
+file format, a vocabulary, a behaviour every call obeys. Those are ordinary documents, edited
+directly, and they are settled enough to build against.
+
+## The site
+
+`site/` is the public page, at `alegauss.github.io/polyweave/` once Pages is pointed at the
+`site` workflow. It says on the page — second, above everything but the hero — how many
+blocks are built and how many lines are still open.
+
+Everything it counts is generated from `docs/ROADMAP.md` through roadkeep rather than typed,
+so the page cannot disagree with the file, and `npm test` fails the build if the stated
+status differs from the roadmap's. See [`site/README.md`](site/README.md).
+
+## More tools by alegauss
+
+For Claude Code:
+
+- **[Claude Code Tray](https://alegauss.github.io/claude-tray/)**: your rate-limit usage as a Windows tray icon that turns red before you run out.
+- **[roadkeep](https://alegauss.github.io/roadkeep/)**: keeps ROADMAP, CHANGELOG and IMPROVEMENTS to one format, as a CLI and a Claude Code plugin.
+- **[commitclerk](https://alegauss.github.io/commitclerk/)**: Conventional Commits messages from your staged diff, in a single-file Python CLI.
+
+For Windows developers:
+
+- **[winwright](https://alegauss.github.io/winwright/)**: drives a Windows desktop app from a test and reports what was actually observed.
+- **[FreeWilly](https://alegauss.github.io/freewilly/)**: Docker on Windows without Docker Desktop, with no admin prompt and no telemetry.
+- **[Quickshell](https://alegauss.github.io/quickshell/)**: an SSH client for Windows with sessions, keys, SFTP and tunnels, and without the rest of the suite.
+
+All of them: [alegauss.github.io](https://alegauss.github.io/)

polyweave_gamekit-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# `polyweave` on PyPI is an unrelated project, so the distribution is named apart and
+# the import stays `polyweave` (§PW602). A remedy that says `pip install` names this.
+name = "polyweave-gamekit"
+dynamic = ["version"]
+description = "Make a game's parts by declaring what each must satisfy: 3D assets, pictures, sound loops and the world's text, on top of Blender, Godot and paid generators."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alexandre Oliveira" }]
+keywords = ["gamedev", "3d", "blender", "godot", "assets", "sound", "mcp", "claude-code"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Multimedia :: Graphics :: 3D Modeling",
+]
+# Both are what a pixel question needs and neither is exotic: Blender bundles numpy, and
+# the assertions and measurements here would otherwise decode PNG by hand.
+dependencies = ["numpy>=1.26", "pillow>=10"]
+
+# 3.11 is Blender 4.2's interpreter. Code here may have to run inside it, so nothing
+# below that line is available to this package.
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-xdist>=3", "ruff>=0.6"]
+# Blender is optional: `capabilities()` reports whether it is reachable and a render
+# refuses without it, so importing polyweave never costs a renderer. The module route is
+# what a worker uses; a blender binary named in `[paths]` is the other one.
+blender = ["bpy>=4.2"]
+# Rendering a score (§PW187) loads Surge XT and runs the mix through Pedalboard. Optional
+# like Blender: music.render refuses by name without it, and nothing else imports it.
+audio = ["pedalboard>=0.9"]
+# Splitting a recorded track into stems (§PW558). Optional the same way, and heavy (torch):
+# sound.stems refuses by name without it. CPU torch is enough.
+stems = ["demucs>=4"]
+# Outlining an SVG's live text before the engine draws it (§PW453). Optional the same
+# way: an SVG with no text never imports it, and one with text refuses by name.
+text = ["fonttools>=4.40"]
+
+# `polyweave <operation>` once pip has installed it: the same command line as
+# `python -m polyweave`, which the plugin's server and hooks keep using.
+[project.scripts]
+polyweave = "polyweave.surface.cli:main"
+
+[project.urls]
+Homepage = "https://alegauss.github.io/polyweave/"
+Source = "https://github.com/alegauss/polyweave"
+Issues = "https://github.com/alegauss/polyweave/issues"
+
+# One number for the package, the MCP server's serverInfo and the provenance record; the
+# plugin manifest is held to it by tests/test_packaging.py.
+[tool.hatch.version]
+path = "src/polyweave/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/polyweave", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/polyweave"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+addopts = "-q"
+markers = [
+    "serial: measures time on the machine, so the gate runs it alone after the rest",
+]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+target-version = "py311"
+# The hooks under `.claude` are this repository's plumbing rather than the plugin, and
+# they predate any lint config here. The migration fixtures are two consumers' scripts
+# copied as they were, which is what tests/test_migrate.py reads, so they are not ours
+# to lint.
+extend-exclude = [".claude", "tests/fixtures/migrate"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

polyweave_gamekit-0.1.0/src/polyweave/__init__.py

@@ -0,0 +1,66 @@
+"""polyweave — a game's parts declared rather than dialled in.
+
+Nothing is imported here on purpose. The caller is an agent whose turn is the budget,
+and a package that pulls in its whole surface to answer one call spends that budget
+before the call happens.
+
+The one function here keeps that rule: `readable()` imports `sys` inside itself, and a
+caller that never calls it pays nothing for it.
+
+The package is laid out by which way its dependencies are meant to run (§PW499):
+
+- `kernel/`: errors and doors, the operation registry, config, jobs, files, the cache,
+  the post-checks and the provenance record. It knows no medium.
+- `loop/`: accept, measure, search, calibrate, verdict, review, brief, revision and the
+  loop's own ledger: what every medium is declared, measured, searched and judged by.
+- `layers/<medium>/`: geometry (with render), picture, sound, words, vfx, motion,
+  engine, reference, store and kits. A measure reading one medium lives with it.
+- `services/`: what was bought from a paid service, and what the service accepts.
+- `surface/`: the server, the command line, the census, capabilities and the calls
+  that adopt a project whole.
+
+A module that fits no layer cleanly sits with the layer that owns its data.
+"""
+
+__version__ = "0.1.0"
+
+
+def readable() -> list[str]:
+    """Write this process's output as UTF-8, and say which streams moved (§PW73).
+
+    Nothing in this package prints its prose. A refusal's message and remedy, and every
+    line a run reports, are returned for the caller to print — so the encoding of the
+    stream they land on is the caller's process to set, not this one's.
+
+    Left unset on a Windows desk it is the locale's. An em dash then goes out as the
+    single byte 0x97, which is correct cp1252 and nothing is lost writing it; what reads
+    the pipe decodes UTF-8, where that byte is not a character, and shows a lozenge. The
+    loss is at the far end, which is the worse end: the process that wrote the line saw
+    nothing wrong and has nothing to report.
+
+    A library must not reconfigure a process it does not own, so this is a call and not
+    something that happens on import. One line at the top of a runner, before it prints:
+
+        polyweave.readable()
+
+    It returns the streams it changed, which is empty where they were already UTF-8, and
+    it is safe to call twice. `sys` is the only import, so it costs nothing to the turn
+    of a caller that never uses it.
+    """
+    import sys
+
+    moved = []
+    for name in ("stdout", "stderr"):
+        stream = getattr(sys, name, None)
+        if stream is None or not hasattr(stream, "reconfigure"):
+            continue
+        if (getattr(stream, "encoding", "") or "").lower().replace("-", "") == "utf8":
+            continue
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except (AttributeError, ValueError, OSError):
+            # A stream that cannot be reconfigured is one somebody else already wrapped,
+            # and taking it over would be the reach this call exists to avoid.
+            continue
+        moved.append(name)
+    return moved

polyweave_gamekit-0.1.0/src/polyweave/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m polyweave`, the command line in `cli.py`."""
+
+import sys
+
+from .surface.cli import main
+
+sys.exit(main())

polyweave_gamekit-0.1.0/src/polyweave/kernel/__init__.py

@@ -0,0 +1 @@
+"""What every layer stands on: errors, the registry, config, jobs, records."""

polyweave_gamekit-0.1.0/src/polyweave/kernel/cache.py

@@ -0,0 +1,182 @@
+"""Renders are content-addressed, so the same picture is paid for once.
+
+The evidence is §PW14: a search revisits neighbourhoods and a caller re-runs the same
+render across sessions, and without a cache every one of those is paid again at the full
+price of a path trace.
+
+The key is the provenance record's own subset — the input hashes, the parameter values,
+the renderer version, the colour pipeline and the seed. Everything that can change the
+output is in it and nothing that cannot, which is what makes a hit **safe to return**
+rather than merely likely to be right.
+
+    key = provenance.cache_key(provenance.planned(...))   # before anything is rendered
+    hit = look(key, work=...)                             # or None
+    put(key, artefact, record, work=...)                  # after a miss
+
+Two things matter more than they look. **A hit is reported as a hit**, because a caller
+timing a sweep needs to know what it actually measured. And **preview rungs are cached
+too**, since those are the renders a search asks for thousands of times while the full
+ones are asked for once.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import shutil
+import time
+from pathlib import Path
+
+from .errors import PolyweaveError
+from .files import read_text_retrying, write_atomic
+
+#: Under the project, so it can be inspected and deleted by hand. `[paths] work` is the
+#: only location the plugin chooses for itself, and it belongs in `.gitignore`.
+DIRECTORY = "cache"
+
+#: What a project may hold before the least recently used are dropped.
+MAX_BYTES = 8_000_000_000
+
+
+def where(work: str | Path) -> Path:
+    return Path(work) / DIRECTORY
+
+
+def slot(key: str, work: str | Path, suffix: str = ".png") -> tuple[Path, Path]:
+    """The artefact and its record, fanned out by the key's first two characters."""
+    if not key or len(key) < 4:
+        raise PolyweaveError(
+            "prov.bad-key",
+            f"{key!r} is not a cache key",
+            "compute it with cache_key over a provenance record",
+        )
+    folder = where(work) / key[:2]
+    return folder / f"{key}{suffix}", folder / f"{key}.json"
+
+
+def look(key: str, *, work: str | Path, suffix: str = ".png") -> dict | None:
+    """What this key holds, or nothing.
+
+    A record whose artefact is missing is **dropped rather than repaired**: half an
+    entry is a hit waiting to return a file that is not there.
+    """
+    artefact, record = slot(key, work, suffix)
+    if not record.is_file():
+        return None
+    if not artefact.is_file():
+        with contextlib.suppress(OSError):
+            record.unlink()
+        return None
+    text = read_text_retrying(record)
+    if text is None:  # pragma: no cover - removed between the two reads
+        return None
+    try:
+        held = json.loads(text)
+    except json.JSONDecodeError:
+        with contextlib.suppress(OSError):
+            record.unlink()
+            artefact.unlink()
+        return None
+    _touch(artefact)
+    return {
+        "key": key,
+        "artefact": artefact,
+        "record": held,
+        "bytes": artefact.stat().st_size,
+    }
+
+
+def put(key: str, artefact: str | Path, record: dict, *, work: str | Path) -> dict:
+    """Keep this artefact under its key, with the record that says what produced it."""
+    source = Path(artefact)
+    if not source.is_file():
+        raise PolyweaveError(
+            "prov.missing-artefact",
+            f"nothing is at {source} to cache",
+            "write the artefact before caching it",
+        )
+    held, beside = slot(key, work, source.suffix or ".png")
+    held.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, held)
+    write_atomic(beside, json.dumps(record, indent=2, sort_keys=True) + "\n")
+    return {"key": key, "artefact": held, "bytes": held.stat().st_size}
+
+
+def take(hit: dict, out: str | Path) -> Path:
+    """Copy a hit out to where the caller wanted it written."""
+    destination = Path(out)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(hit["artefact"], destination)
+    return destination
+
+
+def entries(work: str | Path) -> list[dict]:
+    """Every entry, newest use first."""
+    found = []
+    root = where(work)
+    if not root.is_dir():
+        return found
+    for record in root.rglob("*.json"):
+        key = record.stem
+        artefact = next(
+            (p for p in record.parent.glob(f"{key}.*") if p.suffix != ".json"), None
+        )
+        if artefact is None:
+            with contextlib.suppress(OSError):
+                record.unlink()
+            continue
+        stat = artefact.stat()
+        found.append(
+            {
+                "key": key,
+                "artefact": artefact,
+                "record": record,
+                "bytes": stat.st_size + record.stat().st_size,
+                "used": stat.st_mtime,
+            }
+        )
+    return sorted(found, key=lambda e: e["used"], reverse=True)
+
+
+def stats(work: str | Path) -> dict:
+    held = entries(work)
+    return {
+        "entries": len(held),
+        "bytes": sum(e["bytes"] for e in held),
+        "where": str(where(work)),
+    }
+
+
+def evict(*, work: str | Path, max_bytes: int = MAX_BYTES) -> dict:
+    """Drop the least recently used until the store is under its ceiling."""
+    held = entries(work)
+    total = sum(e["bytes"] for e in held)
+    dropped = []
+    for entry in reversed(held):  # oldest use first
+        if total <= max_bytes:
+            break
+        for path in (entry["artefact"], entry["record"]):
+            with contextlib.suppress(OSError):
+                path.unlink()
+        total -= entry["bytes"]
+        dropped.append(entry["key"])
+    return {"dropped": dropped, "bytes": total, "entries": len(held) - len(dropped)}
+
+
+def forget(key: str, *, work: str | Path, suffix: str = ".png") -> bool:
+    artefact, record = slot(key, work, suffix)
+    gone = False
+    for path in (artefact, record):
+        if path.is_file():
+            with contextlib.suppress(OSError):
+                path.unlink()
+                gone = True
+    return gone
+
+
+def _touch(path: Path) -> None:
+    """Mark an entry as used now, which is what least-recently-used is measured on."""
+    with contextlib.suppress(OSError):
+        now = time.time()
+        os.utime(path, (now, now))