From 949cf5c6312e0cfd270223ec0148267277523fb8 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 18:07:57 +0000
Subject: [PATCH 01/11] Record pytest worker process exits around teardown
Keep OS return codes distinct from pytest status and label observations taken after existing worker teardown. Retain bounded artifacts and job-log evidence without changing test outcomes.
Signed-off-by: zlareb1
---
.github/workflows/ci.yml | 3 +-
tests/_worker_status.py | 169 ++++++++++++++++++++++++
tests/unit/test_worker_status.py | 213 +++++++++++++++++++++++++++++++
3 files changed, 384 insertions(+), 1 deletion(-)
create mode 100644 tests/_worker_status.py
create mode 100644 tests/unit/test_worker_status.py
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fea3440120..4c6e07484b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -193,7 +193,7 @@ jobs:
run: |
SEED="${{ github.run_id }}${{ github.run_attempt }}"
echo "pytest-randomly seed: $SEED"
- pytest tests/unit -vv -n auto -p randomly --randomly-seed="$SEED" --durations=15 \
+ pytest tests/unit -vv -n auto -p randomly -p tests._worker_status --randomly-seed="$SEED" --durations=15 \
-o faulthandler_timeout=300 \
--cov=server --cov=sdk/python/loom --cov-branch --cov-report= \
--junitxml=junit-unit-${{ matrix.part }}.xml
@@ -206,6 +206,7 @@ jobs:
path: |
.coverage.unit-${{ matrix.part }}
junit-unit-${{ matrix.part }}.xml
+ .pytest_cache/worker-status/
include-hidden-files: true
if-no-files-found: warn
# A re-run of one failed part replaces the data its first attempt uploaded.
diff --git a/tests/_worker_status.py b/tests/_worker_status.py
new file mode 100644
index 0000000000..c7bebc9ac7
--- /dev/null
+++ b/tests/_worker_status.py
@@ -0,0 +1,169 @@
+"""Retain bounded OS worker status observations beside pytest's own results."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+if TYPE_CHECKING:
+ from collections.abc import Generator
+
+ from xdist.workermanage import WorkerController
+
+MAX_HANDLES = 64
+# An interrupted worker can notify node-down twice; reserve both teardown records too.
+MAX_RECORDS = 4 * MAX_HANDLES + 3
+MAX_RECORD_BYTES = 2048
+ARTIFACT_ROOT = Path(".pytest_cache/worker-status")
+
+
+def _versions() -> dict[str, str]:
+ versions = {}
+ for package in ("pytest", "pytest-xdist", "execnet"):
+ try:
+ versions[package] = version(package)
+ except (PackageNotFoundError, OSError):
+ versions[package] = "unknown"
+ return versions
+
+
+class WorkerStatus:
+ def __init__(self, config: pytest.Config) -> None:
+ self.config = config
+ self.handles: dict[WorkerController, Any] = {}
+ self.records = 0
+ self.path: Path | None = None
+ self.dropped_handles = 0
+ try:
+ root = config.rootpath / ARTIFACT_ROOT
+ root.mkdir(parents=True, exist_ok=True)
+ self.path = Path(tempfile.mkdtemp(prefix="session-", dir=root)) / "status.jsonl"
+ except OSError:
+ pass # The job log still carries observations when artifact creation fails.
+
+ def emit(self, record: dict[str, Any]) -> None:
+ if self.records >= MAX_RECORDS:
+ return
+ if self.records == MAX_RECORDS - 1:
+ record = {"event": "record_limit", "limit": MAX_RECORDS}
+ self.records += 1
+ record = {**record, "sequence": self.records, "artifact_available": self.path is not None}
+ line = _encode(record)
+ if self.path is not None:
+ try:
+ with self.path.open("a") as output:
+ output.write(line)
+ except OSError:
+ self.path = None
+ record.update(artifact_available=False, artifact_write_failed=True)
+ line = _encode(record)
+ try:
+ reporter = self.config.pluginmanager.getplugin("terminalreporter")
+ if reporter is not None:
+ reporter.write_line("[worker-status] " + line.rstrip())
+ else:
+ sys.stderr.write("[worker-status] " + line)
+ except (OSError, ValueError):
+ pass # Diagnostics must preserve the original pytest result if output closes.
+
+ @pytest.hookimpl(tryfirst=True)
+ def pytest_sessionstart(self) -> None:
+ self.emit(
+ {
+ "event": "context",
+ "python": sys.version.split()[0],
+ "platform": sys.platform,
+ "versions": _versions(),
+ "environment": {
+ key: os.environ[key][:128]
+ for key in (
+ "GITHUB_RUN_ID",
+ "GITHUB_RUN_ATTEMPT",
+ "GITHUB_JOB",
+ "GITHUB_SHA",
+ "LOOM_TEST_SHARD",
+ )
+ if key in os.environ
+ },
+ "seed": self.config.getoption("randomly_seed", default=None),
+ "workers": self.config.getoption("numprocesses", default=None),
+ "faulthandler_timeout": self.config.getini("faulthandler_timeout"),
+ "faulthandler_exit_on_timeout": self.config.getini("faulthandler_exit_on_timeout"),
+ }
+ )
+
+ @pytest.hookimpl(optionalhook=True)
+ def pytest_configure_node(self, node: WorkerController) -> None:
+ if node in self.handles:
+ return
+ if len(self.handles) >= MAX_HANDLES:
+ self.dropped_handles += 1
+ return
+ spec = node.gateway.spec
+ # An ssh/via gateway's local process status is not the remote worker's status.
+ process = None
+ if spec.popen and not spec.via:
+ process = getattr(getattr(node.gateway, "_io", None), "popen", None)
+ self.handles[node] = process
+
+ def observe(self, node: WorkerController, stage: str, error: object | None = None) -> None:
+ process = self.handles[node]
+ returncode = None
+ state = "unavailable" if process is None else "unknown"
+ try:
+ if process is not None:
+ returncode = process.poll()
+ state = "running" if returncode is None else "exited"
+ except Exception as e: # noqa: BLE001 — diagnostic failure must not replace pytest's outcome
+ state = type(e).__name__[:64]
+ output = getattr(node, "workeroutput", {})
+ self.emit(
+ {
+ "event": "worker_status",
+ "stage": stage,
+ "worker": node.gateway.id[:64],
+ "pid": getattr(process, "pid", None),
+ "os_state": state,
+ "os_returncode": returncode,
+ "os_signal": -returncode if returncode is not None and returncode < 0 else None,
+ "pytest_exitstatus": output.get("exitstatus"),
+ "channel_error_type": type(error).__name__[:64] if error is not None else None,
+ }
+ )
+
+ @pytest.hookimpl(optionalhook=True)
+ def pytest_testnodedown(self, node: WorkerController, error: object | None) -> None:
+ if node not in self.handles:
+ self.pytest_configure_node(node)
+ if node in self.handles:
+ self.observe(node, "node_down", error)
+
+ @pytest.hookimpl(wrapper=True, tryfirst=True)
+ def pytest_sessionfinish(self) -> Generator[None, object, object]:
+ for node in self.handles:
+ self.observe(node, "before_teardown")
+ try:
+ return (yield)
+ finally:
+ for node in self.handles:
+ self.observe(node, "after_teardown")
+ self.emit({"event": "collection_end", "dropped_handles": self.dropped_handles})
+
+
+def pytest_configure(config: pytest.Config) -> None:
+ if not hasattr(config, "workerinput"):
+ config.pluginmanager.register(WorkerStatus(config), "worker-terminal-status")
+
+
+def _encode(record: dict[str, Any]) -> str:
+ line = json.dumps(record, ensure_ascii=True, separators=(",", ":")) + "\n"
+ if len(line.encode()) > MAX_RECORD_BYTES:
+ return '{"event":"record_too_large"}\n'
+ return line
diff --git a/tests/unit/test_worker_status.py b/tests/unit/test_worker_status.py
new file mode 100644
index 0000000000..de42c9ce68
--- /dev/null
+++ b/tests/unit/test_worker_status.py
@@ -0,0 +1,213 @@
+"""Worker observations preserve terminal uncertainty and pytest outcomes."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from types import SimpleNamespace
+from xml.etree import ElementTree
+
+import pytest
+
+from tests import _worker_status as w
+
+pytest_plugins = ("pytester",)
+
+
+class Process:
+ pid = 123
+
+ def __init__(self, *codes: int | None, error: Exception | None = None):
+ self.codes = iter(codes)
+ self.error = error
+ self.calls = 0
+
+ def poll(self):
+ self.calls += 1
+ if self.error:
+ raise self.error
+ return next(self.codes)
+
+
+class Node:
+ def __init__(self, process, *, popen=True, via=None):
+ self.gateway = SimpleNamespace(
+ id="gw0", spec=SimpleNamespace(popen=popen, via=via), _io=SimpleNamespace(popen=process)
+ )
+ self.workeroutput = {"exitstatus": 1}
+
+
+@pytest.fixture
+def collector(tmp_path):
+ config = SimpleNamespace(
+ rootpath=tmp_path,
+ pluginmanager=SimpleNamespace(getplugin=lambda _: None),
+ getoption=lambda name, default=None: {"randomly_seed": 1729, "numprocesses": 2}.get(
+ name, default
+ ),
+ getini=lambda name: {"faulthandler_timeout": 300, "faulthandler_exit_on_timeout": False}[
+ name
+ ],
+ )
+ return w.WorkerStatus(config)
+
+
+def records(collector):
+ return [json.loads(line) for line in collector.path.read_text().splitlines()]
+
+
+@pytest.mark.parametrize("code", [None, 0, 7, -9, -11])
+def test_node_down_distinguishes_os_status_from_pytest_status(collector, code):
+ process = Process(code)
+ collector.pytest_testnodedown(Node(process), "Not properly terminated")
+ record = records(collector)[0]
+ assert record["stage"] == "node_down"
+ assert record["pid"] == 123
+ assert record["os_returncode"] == code
+ assert record["os_signal"] == (-code if code is not None and code < 0 else None)
+ assert record["os_state"] == ("running" if code is None else "exited")
+ assert record["pytest_exitstatus"] == 1
+ assert process.calls == 1
+
+
+def test_status_first_observed_after_teardown_keeps_its_stage(collector):
+ node = Node(Process(None, None, -9))
+ collector.pytest_testnodedown(node, "channel lost")
+ finish = collector.pytest_sessionfinish()
+ next(finish)
+ sentinel = object()
+ with pytest.raises(StopIteration) as stopped:
+ finish.send(sentinel)
+ assert stopped.value.value is sentinel
+ observations = records(collector)[:3]
+ assert [r["stage"] for r in observations] == [
+ "node_down",
+ "before_teardown",
+ "after_teardown",
+ ]
+ assert [r["os_returncode"] for r in observations] == [None, None, -9]
+
+
+def test_existing_teardown_exception_is_preserved(collector):
+ collector.pytest_configure_node(Node(Process(None, 0)))
+ finish = collector.pytest_sessionfinish()
+ next(finish)
+ original = RuntimeError("existing teardown failure")
+ with pytest.raises(RuntimeError) as raised:
+ finish.throw(original)
+ assert raised.value is original
+ assert records(collector)[1]["stage"] == "after_teardown"
+
+
+@pytest.mark.parametrize("popen,via", [(False, None), (True, "gateway")])
+def test_nonlocal_gateway_is_unavailable_without_polling(collector, popen, via):
+ process = Process(error=AssertionError("must not poll remote transport"))
+ collector.pytest_testnodedown(Node(process, popen=popen, via=via), None)
+ record = records(collector)[0]
+ assert record["os_returncode"] is None
+ assert record["os_state"] == "unavailable"
+ assert process.calls == 0
+
+
+def test_poll_failure_stays_unknown_without_losing_pytest_status(collector):
+ collector.pytest_testnodedown(Node(Process(error=OSError("unavailable"))), None)
+ record = records(collector)[0]
+ assert record["os_returncode"] is None
+ assert record["os_signal"] is None
+ assert record["os_state"] == "OSError"
+ assert record["pytest_exitstatus"] == 1
+
+
+def test_artifact_write_failure_keeps_the_observation_in_the_log(collector, capsys):
+ collector.path = collector.config.rootpath / "absent" / "status.jsonl"
+ collector.pytest_testnodedown(Node(Process(-11)), None)
+ record = json.loads(capsys.readouterr().err.removeprefix("[worker-status] "))
+ assert record["os_signal"] == 11
+ assert record["artifact_write_failed"] is True
+ assert record["artifact_available"] is False
+
+
+def test_records_and_retained_handles_are_bounded(collector, capsys):
+ for _ in range(w.MAX_HANDLES + 3):
+ collector.pytest_configure_node(Node(Process()))
+ assert len(collector.handles) == w.MAX_HANDLES
+ assert collector.dropped_handles == 3
+ for _ in range(w.MAX_RECORDS + 3):
+ collector.emit({"event": "synthetic"})
+ assert len(records(collector)) == w.MAX_RECORDS
+ assert records(collector)[-1]["event"] == "record_limit"
+ assert collector.path.stat().st_size <= w.MAX_RECORDS * w.MAX_RECORD_BYTES
+ assert len(capsys.readouterr().err.splitlines()) == w.MAX_RECORDS
+ assert len(w._encode({"value": "x" * w.MAX_RECORD_BYTES}).encode()) <= w.MAX_RECORD_BYTES
+
+
+def test_context_contains_only_allowlisted_environment(collector, monkeypatch):
+ monkeypatch.setenv("GITHUB_RUN_ID", "42")
+ monkeypatch.setenv("PRIVATE_TOKEN", "must not appear")
+ collector.pytest_sessionstart()
+ context = records(collector)[0]
+ assert context["environment"]["GITHUB_RUN_ID"] == "42"
+ assert "PRIVATE_TOKEN" not in context["environment"]
+ assert context["seed"] == 1729
+ assert context["faulthandler_timeout"] == 300
+ assert context["faulthandler_exit_on_timeout"] is False
+
+
+def test_every_retained_handle_gets_post_teardown_evidence(collector):
+ collector.pytest_sessionstart()
+ for _ in range(w.MAX_HANDLES):
+ node = Node(Process(None, None, None, 0))
+ node.workeroutput["exitstatus"] = 2
+ collector.pytest_testnodedown(node, None)
+ collector.pytest_testnodedown(node, "keyboard-interrupt")
+ finish = collector.pytest_sessionfinish()
+ next(finish)
+ with pytest.raises(StopIteration):
+ next(finish)
+ observed = records(collector)
+ after = [r for r in observed if r.get("stage") == "after_teardown"]
+ assert len(after) == w.MAX_HANDLES
+ assert all(r["os_returncode"] == 0 for r in after)
+ assert observed[-1] == {
+ "event": "collection_end",
+ "dropped_handles": 0,
+ "sequence": 4 * w.MAX_HANDLES + 2,
+ "artifact_available": True,
+ }
+
+
+def test_plugin_preserves_real_pytest_failures_and_junit(pytester, monkeypatch):
+ monkeypatch.setenv("PYTEST_DISABLE_PLUGIN_AUTOLOAD", "1")
+ monkeypatch.setenv("PYTHONPATH", str(Path(__file__).resolve().parents[2]))
+ monkeypatch.setenv("PYTEST_ADDOPTS", "")
+ pytester.makepyfile(
+ """
+ def test_pass():
+ assert 1 == 1
+ def test_assertion():
+ assert False, "original assertion"
+ def test_exception():
+ raise ValueError("original exception")
+ """
+ )
+ outcomes = []
+ for enabled in (False, True):
+ report = pytester.path / f"result-{enabled}.xml"
+ args = ["-p", "xdist.plugin", "-n", "1", f"--junitxml={report}"]
+ if enabled:
+ args += ["-p", "tests._worker_status"]
+ result = pytester.runpytest_subprocess(*args)
+ result.assert_outcomes(passed=1, failed=2)
+ assert result.ret == pytest.ExitCode.TESTS_FAILED
+ cases = ElementTree.parse(report).findall(".//testcase")
+ outcomes.append(sorted((c.attrib["name"], c.find("failure") is not None) for c in cases))
+ assert "original assertion" in result.stdout.str()
+ assert "original exception" in result.stdout.str()
+ assert outcomes[0] == outcomes[1]
+ files = list((pytester.path / w.ARTIFACT_ROOT).glob("*/status.jsonl"))
+ assert len(files) == 1 # The explicitly loaded plugin does not run inside workers.
+ observed = [json.loads(line) for line in files[0].read_text().splitlines()]
+ statuses = [r for r in observed if r["event"] == "worker_status"]
+ assert [r["stage"] for r in statuses] == ["node_down", "before_teardown", "after_teardown"]
+ assert statuses[-1]["os_returncode"] == 0
+ assert statuses[-1]["pytest_exitstatus"] == 1
From 7980fa99baa3758bed037fe6acf73bc35a2e2d51 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 18:21:57 +0000
Subject: [PATCH 02/11] Collection admins can configure spend caps and warnings
Add a collection budget operation and Library control while preserving the namespace registration guard and existing budget enforcement.
Signed-off-by: zlareb1
---
docs/architecture/sharing.md | 16 ++
docs/reference/operations.md | 3 +-
docs/reference/operations/collection.md | 22 ++
docs/reference/status.md | 4 +-
frontend/src/api/collections.ts | 15 ++
.../src/flows/CollectionBudgetDialog.test.tsx | 123 +++++++++
frontend/src/flows/CollectionBudgetDialog.tsx | 162 ++++++++++++
frontend/src/views/LibraryCollections.tsx | 15 ++
sdk/python/loom/client.py | 9 +
sdk/python/loom/ops.py | 42 ++++
sdk/typescript/src/generated/ops.ts | 24 +-
server/identity/api/models_collections.py | 35 +++
server/identity/api/ops_collections.py | 15 ++
server/identity/app/collection_budgets.py | 58 +++++
server/operations/reach_manifest.py | 1 +
server/settings/catalog.py | 1 +
tests/integration/test_knowledge_sharing.py | 64 +++++
tests/unit/snapshots/sdk_public_api.json | 4 +
tests/unit/test_collection_budgets.py | 235 ++++++++++++++++++
19 files changed, 844 insertions(+), 4 deletions(-)
create mode 100644 frontend/src/flows/CollectionBudgetDialog.test.tsx
create mode 100644 frontend/src/flows/CollectionBudgetDialog.tsx
create mode 100644 server/identity/app/collection_budgets.py
create mode 100644 tests/unit/test_collection_budgets.py
diff --git a/docs/architecture/sharing.md b/docs/architecture/sharing.md
index a3e7981929..109a82f9a4 100644
--- a/docs/architecture/sharing.md
+++ b/docs/architecture/sharing.md
@@ -112,6 +112,22 @@ feature page). A client draws a conversation's saved state with one
`conversation.saved_status` call, and a user erasure takes the user's conversation rows,
saved ones included.
+## Collection spend policy
+
+`collection.budget_set` lets a collection's admin change its rolling 24-hour USD cap,
+its separate named-user cap and its budget warning inbox. An omitted field keeps its
+stored value; a zero cap inherits the server default, and an empty inbox disables
+warnings. A warning inbox must belong to the same collection. Personal, missing and
+retired collections cannot be configured through this operation.
+
+The audited operation holds the directory-row claim from read through write and carries
+every unrelated directory column forward. It changes no collection membership, tree,
+visibility or login state. `namespace.register` continues to refuse collection names.
+Budget status and admission guards read the same directory columns for collections as
+for other namespaces; the operation changes no spend events or enforcement thresholds.
+Both adjacent builds read the same stored fields, so the operation requires no schema
+change. The Library's collection menu provides the same budget controls.
+
## Identity
A service in front of Loom (a chat app) signs a short-lived token for each request it
diff --git a/docs/reference/operations.md b/docs/reference/operations.md
index 1d3669e930..64aa8db19e 100644
--- a/docs/reference/operations.md
+++ b/docs/reference/operations.md
@@ -123,7 +123,7 @@ python scripts/codegen/docs_reference.py --check # exit 1 when a region is stal
-375 operations in 43 groups. Every op is served at `POST /v1/` and as the MCP tool `loom_` (dots become underscores).
+376 operations in 43 groups. Every op is served at `POST /v1/` and as the MCP tool `loom_` (dots become underscores).
Columns: **Role** is the minimum role (`viewer` < `writer` < `admin` < `org_admin` < `platform_admin`); **Kind** is `read` (idempotent, viewer, unaudited, writes nothing — MCP `readOnlyHint`), `idempotent` (safe to retry) or `write`; **Listed under `all`** says whether an MCP connection on the `all` toolset lists the op in `tools/list` (`code.*` ops only with `LOOM_MCP_CODE_TOOLS=true`); an op marked `no` is still callable by name or through `loom_op`, unless it is hidden from MCP; **Audit** marks ops that leave an `audit_log` row.
@@ -245,6 +245,7 @@ Fields for every `collection` op: [operations/collection.md](operations/collecti
| Operation | Summary | Role | Kind | Listed under `all` | Audit |
| --- | --- | --- | --- | --- | --- |
+| [`collection.budget_set`](operations/collection.md#collectionbudget_set) | Change only a collection's spend caps and warning destination. | admin | idempotent | no | yes |
| [`collection.create`](operations/collection.md#collectioncreate) | Create a collection: a namespace read and written only through grants. | viewer | idempotent | no | yes |
| [`collection.delete`](operations/collection.md#collectiondelete) | Delete a collection with what it holds: a purging erasure of the namespace (documents, chunks, originals, memory leave the disk), then it leaves the directory and the tree, and its name is never used… | admin | idempotent | no | yes |
| [`collection.list`](operations/collection.md#collectionlist) | List the collections the caller can read, by name. | viewer | read | no | |
diff --git a/docs/reference/operations/collection.md b/docs/reference/operations/collection.md
index c6923c62ae..e3e9d8619d 100644
--- a/docs/reference/operations/collection.md
+++ b/docs/reference/operations/collection.md
@@ -8,6 +8,28 @@ Every op is `POST /v1/` over HTTP and the MCP tool `loom_`. The identity
+## `collection.budget_set`
+
+Change only a collection's spend caps and warning destination.
+
+`POST /v1/collection.budget_set` · MCP `loom_collection_budget_set` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset
+
+| Input field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `org` | `str` | required | The tenant (first element of the identity tuple). |
+| `namespace` | `str` | required | The namespace the op reads or writes. |
+| `daily_cost_cap_usd` | `float \| None` | `None` | Collection cap in USD per rolling 24 hours; 0 inherits the server default, omit keeps it. |
+| `daily_user_cost_cap_usd` | `float \| None` | `None` | Named-user cap in USD per rolling 24 hours; 0 inherits the server default, omit keeps it. |
+| `budget_alert_inbox` | `str \| None` | `None` | An existing task inbox owned by this collection; '' disables warnings, omit keeps it. |
+
+| Output field | Type | Meaning |
+| --- | --- | --- |
+| `namespace` | `str` | The namespace the op reads or writes. |
+| `changed` | `bool` | |
+| `daily_cost_cap_usd` | `float` | |
+| `daily_user_cost_cap_usd` | `float` | |
+| `budget_alert_inbox` | `str` | |
+
## `collection.create`
Create a collection: a namespace read and written only through grants.
diff --git a/docs/reference/status.md b/docs/reference/status.md
index 8071866f40..5136ca1df5 100644
--- a/docs/reference/status.md
+++ b/docs/reference/status.md
@@ -25,7 +25,7 @@ serves is in the [MCP reference](./mcp.md#toolsets).
-375 operations, 261 of them experimental.
+376 operations, 262 of them experimental.
| Group | Stable | Experimental |
| --- | --- | --- |
@@ -36,7 +36,7 @@ serves is in the [MCP reference](./mcp.md#toolsets).
| `blacklist` | 1 | [`blacklist.add`](operations/blacklist.md#blacklistadd), [`blacklist.remove`](operations/blacklist.md#blacklistremove), [`blacklist.sweep`](operations/blacklist.md#blacklistsweep) |
| `calibration` | 0 | [`calibration.get`](operations/calibration.md#calibrationget) |
| `code` | 28 | [`code.backport_gap`](operations/code.md#codebackport_gap), [`code.backport_gaps`](operations/code.md#codebackport_gaps), [`code.bisect_candidates`](operations/code.md#codebisect_candidates), [`code.blame_range`](operations/code.md#codeblame_range), [`code.callees`](operations/code.md#codecallees), [`code.conventions`](operations/code.md#codeconventions), [`code.coverage_claim`](operations/code.md#codecoverage_claim), [`code.examples`](operations/code.md#codeexamples), [`code.files`](operations/code.md#codefiles), [`code.first_build`](operations/code.md#codefirst_build), [`code.map`](operations/code.md#codemap), [`code.outline`](operations/code.md#codeoutline), [`code.path_guards`](operations/code.md#codepath_guards), [`code.pr_check`](operations/code.md#codepr_check), [`code.reindex`](operations/code.md#codereindex), [`code.repo.set_access`](operations/code.md#codereposet_access), [`code.repo.set_source`](operations/code.md#codereposet_source), [`code.review_brief`](operations/code.md#codereview_brief), [`code.setting_facts`](operations/code.md#codesetting_facts), [`code.symbol_history`](operations/code.md#codesymbol_history), [`code.test_gate`](operations/code.md#codetest_gate), [`code.test_home`](operations/code.md#codetest_home), [`code.tests_for`](operations/code.md#codetests_for), [`code.verify_citations`](operations/code.md#codeverify_citations) |
-| `collection` | 0 | [`collection.create`](operations/collection.md#collectioncreate), [`collection.delete`](operations/collection.md#collectiondelete), [`collection.list`](operations/collection.md#collectionlist), [`collection.move`](operations/collection.md#collectionmove) |
+| `collection` | 0 | [`collection.budget_set`](operations/collection.md#collectionbudget_set), [`collection.create`](operations/collection.md#collectioncreate), [`collection.delete`](operations/collection.md#collectiondelete), [`collection.list`](operations/collection.md#collectionlist), [`collection.move`](operations/collection.md#collectionmove) |
| `conflicts` | 2 | [`conflicts.allowlist_list`](operations/conflicts.md#conflictsallowlist_list), [`conflicts.allowlist_remove`](operations/conflicts.md#conflictsallowlist_remove), [`conflicts.propose_revision`](operations/conflicts.md#conflictspropose_revision) |
| `connection` | 0 | [`connection.disconnect`](operations/connection.md#connectiondisconnect), [`connection.list`](operations/connection.md#connectionlist) |
| `consolidations` | 0 | [`consolidations.list`](operations/consolidations.md#consolidationslist) |
diff --git a/frontend/src/api/collections.ts b/frontend/src/api/collections.ts
index 025e51741f..4ebcc47d7e 100644
--- a/frontend/src/api/collections.ts
+++ b/frontend/src/api/collections.ts
@@ -7,6 +7,21 @@ import { COLLECTIONS_PAGE } from "../lib/collections";
// ===== Collections =====
+export interface CollectionBudgetPolicy {
+ daily_cost_cap_usd: number;
+ daily_user_cost_cap_usd: number;
+ budget_alert_inbox: string;
+}
+
+/** Change only the explicitly supplied spend policy fields of an administered collection. */
+export async function setCollectionBudget(
+ org: string,
+ namespace: string,
+ patch: Partial,
+): Promise {
+ return post("/v1/collection.budget_set", { ...patch, org, namespace });
+}
+
/** Mirrors `server/identity/api/models_collections.py::_CollectionEntry`. */
export interface CollectionEntry {
namespace: string;
diff --git a/frontend/src/flows/CollectionBudgetDialog.test.tsx b/frontend/src/flows/CollectionBudgetDialog.test.tsx
new file mode 100644
index 0000000000..911547f354
--- /dev/null
+++ b/frontend/src/flows/CollectionBudgetDialog.test.tsx
@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { act, cleanup, fireEvent, render, screen, waitFor } from "../test/rtl";
+import * as api from "../api";
+import userEvent from "@testing-library/user-event";
+import { CollectionBudgetDialog } from "./CollectionBudgetDialog";
+import { Picker, entry, read } from "../test/libraryCollections";
+import { toast } from "../components/Toast";
+
+vi.mock("../api", async (original) => ({
+ ...(await original()),
+ getNamespace: vi.fn(),
+ setCollectionBudget: vi.fn(),
+}));
+vi.mock("../components/Toast", () => ({ toast: vi.fn(), toastError: vi.fn() }));
+
+beforeEach(() => {
+ vi.mocked(api.getNamespace).mockResolvedValue({
+ namespace: "col-a",
+ daily_cost_cap_usd: 2,
+ daily_user_cost_cap_usd: 1,
+ budget_alert_inbox: "owned",
+ } as api.NamespaceInfo);
+ vi.mocked(api.setCollectionBudget).mockResolvedValue({
+ namespace: "col-a",
+ changed: true,
+ daily_cost_cap_usd: 2,
+ daily_user_cost_cap_usd: 0.5,
+ budget_alert_inbox: "",
+ });
+});
+afterEach(() => {
+ cleanup();
+ vi.clearAllMocks();
+});
+
+it("reads the collection policy and saves only changed budget fields to that collection", async () => {
+ const close = vi.fn();
+ render();
+ const field = await screen.findByLabelText("Daily cap per user (USD)");
+ expect(api.getNamespace).toHaveBeenCalledWith(
+ { org: "o", namespace: "col-a" },
+ expect.objectContaining({ signal: expect.any(AbortSignal) }),
+ );
+ fireEvent.change(field, { target: { value: "0.5" } });
+ fireEvent.change(screen.getByLabelText("Budget warning inbox"), { target: { value: "" } });
+ await act(async () => fireEvent.click(screen.getByRole("button", { name: "Save budget" })));
+ expect(api.setCollectionBudget).toHaveBeenCalledWith("o", "col-a", {
+ daily_user_cost_cap_usd: 0.5,
+ budget_alert_inbox: "",
+ });
+ expect(close).toHaveBeenCalledTimes(1);
+});
+
+it("keeps a failed save open and sends no write before its policy read succeeds", async () => {
+ vi.mocked(api.getNamespace).mockRejectedValueOnce(new Error("Read unavailable"));
+ const close = vi.fn();
+ render();
+ await screen.findByRole("alert");
+ expect(screen.getByRole("button", { name: "Save budget" })).toBeDisabled();
+ expect(api.setCollectionBudget).not.toHaveBeenCalled();
+ expect(close).not.toHaveBeenCalled();
+});
+
+it("retains the draft and the server refusal on a failed write", async () => {
+ vi.mocked(api.setCollectionBudget).mockRejectedValueOnce(new Error("Inbox belongs elsewhere"));
+ const close = vi.fn();
+ render();
+ fireEvent.change(await screen.findByLabelText("Budget warning inbox"), { target: { value: "foreign" } });
+ await act(async () => fireEvent.click(screen.getByRole("button", { name: "Save budget" })));
+ await screen.findByRole("alert");
+ expect(screen.getByLabelText("Budget warning inbox")).toHaveValue("foreign");
+ expect(close).not.toHaveBeenCalled();
+});
+
+it("opens budget controls from the administered Library collection's actual menu", async () => {
+ const c = entry("col-a");
+ const view = render();
+ await userEvent.click(screen.getByRole("button", { name: "Actions for col-a" }));
+ await userEvent.click(await screen.findByRole("menuitem", { name: "Budget…" }));
+ await waitFor(() => expect(screen.getByRole("dialog", { name: "Budget · col-a" })).toBeInTheDocument());
+ expect(await screen.findByLabelText("Daily cost cap (USD)")).toHaveValue(2);
+ const viewer = entry("col-a", { role: "viewer" });
+ view.rerender();
+ await waitFor(() => expect(screen.queryByRole("dialog", { name: "Budget · col-a" })).not.toBeInTheDocument());
+});
+
+it("an old save cannot close a later collection dialog or discard its draft", async () => {
+ let finish!: (value: Awaited>) => void;
+ vi.mocked(api.setCollectionBudget).mockReturnValueOnce(
+ new Promise((resolve) => {
+ finish = resolve;
+ }),
+ );
+ const a = entry("col-a"),
+ b = entry("col-b");
+ const places = read([a, b]);
+ const view = render(
+ ,
+ );
+ await userEvent.click(screen.getByRole("button", { name: "Actions for col-a" }));
+ await userEvent.click(await screen.findByRole("menuitem", { name: "Budget…" }));
+ fireEvent.change(await screen.findByLabelText("Daily cost cap (USD)"), { target: { value: "3" } });
+ await act(async () => fireEvent.click(screen.getByRole("button", { name: "Save budget" })));
+ expect(api.setCollectionBudget).toHaveBeenCalledWith("o", "col-a", { daily_cost_cap_usd: 3 });
+ view.rerender();
+ await waitFor(() => expect(screen.queryByRole("dialog")).not.toBeInTheDocument());
+ await userEvent.click(screen.getByRole("button", { name: "Actions for col-b" }));
+ await userEvent.click(await screen.findByRole("menuitem", { name: "Budget…" }));
+ const draft = await screen.findByLabelText("Daily cost cap (USD)");
+ fireEvent.change(draft, { target: { value: "7" } });
+ await act(async () =>
+ finish({
+ namespace: "col-a",
+ changed: true,
+ daily_cost_cap_usd: 3,
+ daily_user_cost_cap_usd: 1,
+ budget_alert_inbox: "owned",
+ }),
+ );
+ expect(screen.getByRole("dialog", { name: "Budget · col-b" })).toBeInTheDocument();
+ expect(screen.getByLabelText("Daily cost cap (USD)")).toHaveValue(7);
+ expect(toast).not.toHaveBeenCalled();
+});
diff --git a/frontend/src/flows/CollectionBudgetDialog.tsx b/frontend/src/flows/CollectionBudgetDialog.tsx
new file mode 100644
index 0000000000..2879223ad2
--- /dev/null
+++ b/frontend/src/flows/CollectionBudgetDialog.tsx
@@ -0,0 +1,162 @@
+import { useState } from "react";
+import { Button } from "@clickhouse/click-ui/Button";
+import { NumberField } from "@clickhouse/click-ui/NumberField";
+import { TextField } from "@clickhouse/click-ui/TextField";
+import { getNamespace, setCollectionBudget, type CollectionBudgetPolicy, type CollectionEntry } from "../api";
+import { collectionTitle } from "../lib/collections";
+import { humanizeError } from "../lib/errorWords";
+import { useAbortableEffect, useMounted } from "../lib/hooks";
+import { invalidateShared } from "../lib/sharedReads";
+import { Modal, ModalFooter } from "../components/ui/Modal";
+import { Alert, Loading } from "../components/ui";
+import { toast } from "../components/Toast";
+
+/** Mounted per collection and open session, so a draft cannot target another collection. */
+export function CollectionBudgetDialog({
+ org,
+ collection,
+ onClose,
+}: {
+ org: string;
+ collection: CollectionEntry;
+ onClose: () => void;
+}) {
+ const mounted = useMounted();
+ const [stored, setStored] = useState(null);
+ const [cap, setCap] = useState("");
+ const [userCap, setUserCap] = useState("");
+ const [inbox, setInbox] = useState("");
+ const [error, setError] = useState(null);
+ const [busy, setBusy] = useState(false);
+ useAbortableEffect(
+ async (signal, live) => {
+ try {
+ const row = await getNamespace({ org, namespace: collection.namespace }, { signal });
+ if (!live()) return;
+ if (!row) throw new Error("Collection settings not found");
+ const policy = {
+ daily_cost_cap_usd: row.daily_cost_cap_usd ?? 0,
+ daily_user_cost_cap_usd: row.daily_user_cost_cap_usd ?? 0,
+ budget_alert_inbox: row.budget_alert_inbox ?? "",
+ };
+ setStored(policy);
+ setCap(String(policy.daily_cost_cap_usd));
+ setUserCap(String(policy.daily_user_cost_cap_usd));
+ setInbox(policy.budget_alert_inbox);
+ } catch (e) {
+ if (live()) setError(humanizeError(e));
+ }
+ },
+ [org, collection.namespace],
+ );
+
+ const submit = async () => {
+ if (!stored || busy) return;
+ const patch: Partial = {};
+ const next = {
+ daily_cost_cap_usd: Number(cap),
+ daily_user_cost_cap_usd: Number(userCap),
+ budget_alert_inbox: inbox.trim(),
+ };
+ if (
+ !cap.trim() ||
+ !userCap.trim() ||
+ !Number.isFinite(next.daily_cost_cap_usd) ||
+ next.daily_cost_cap_usd < 0 ||
+ !Number.isFinite(next.daily_user_cost_cap_usd) ||
+ next.daily_user_cost_cap_usd < 0
+ ) {
+ setError("Caps must be finite, non-negative numbers");
+ return;
+ }
+ if (next.daily_cost_cap_usd !== stored.daily_cost_cap_usd) patch.daily_cost_cap_usd = next.daily_cost_cap_usd;
+ if (next.daily_user_cost_cap_usd !== stored.daily_user_cost_cap_usd)
+ patch.daily_user_cost_cap_usd = next.daily_user_cost_cap_usd;
+ if (next.budget_alert_inbox !== stored.budget_alert_inbox) patch.budget_alert_inbox = next.budget_alert_inbox;
+ if (!Object.keys(patch).length) {
+ onClose();
+ return;
+ }
+ setBusy(true);
+ setError(null);
+ try {
+ await setCollectionBudget(org, collection.namespace, patch);
+ invalidateShared(`budget:${org}/${collection.namespace}`);
+ if (!mounted.current) return;
+ toast("Budget settings saved", "ok");
+ onClose();
+ } catch (e) {
+ if (mounted.current) setError(humanizeError(e));
+ } finally {
+ if (mounted.current) setBusy(false);
+ }
+ };
+ return (
+ !open && !busy && onClose()}
+ title={`Budget · ${collectionTitle(collection)}`}
+ className="w-full max-w-[480px]"
+ >
+
+
+ );
+}
diff --git a/frontend/src/views/LibraryCollections.tsx b/frontend/src/views/LibraryCollections.tsx
index e9358e805a..1c4de520f5 100644
--- a/frontend/src/views/LibraryCollections.tsx
+++ b/frontend/src/views/LibraryCollections.tsx
@@ -10,6 +10,7 @@ import { confirmAction } from "../components/ConfirmDialog";
import { toast, toastError } from "../components/Toast";
import { type ClaimCreateVersion, CreateCollectionDialog } from "../flows/CreateCollectionDialog";
import { MoveCollectionDialog } from "../flows/MoveCollectionDialog";
+import { CollectionBudgetDialog } from "../flows/CollectionBudgetDialog";
import { CollectionBack, CollectionChips, CollectionPath, cycleStart } from "./LibraryHierarchy";
import {
COLLECTIONS_LISTED,
@@ -256,6 +257,7 @@ export function LibraryCollections({
}) {
const all = place === ALL_DOCUMENTS;
const [moving, setMoving] = useState(null);
+ const [budgeting, setBudgeting] = useState(null);
const { rows, error } = collections;
// New collection and Move belong to the place they opened in: a move to another
// closes them, and coming back does not reopen them. The list answering (or read again)
@@ -263,7 +265,11 @@ export function LibraryCollections({
useEffect(() => {
setCreating(false);
setMoving(null);
+ setBudgeting(null);
}, [place]);
+ useEffect(() => {
+ setBudgeting(null);
+ }, [org, current?.namespace, current?.role]);
// The select's order; beside the tree there is no select.
const ordered = useMemo(() => (besideTree ? [] : treeOrder(rows ?? [])), [rows, besideTree]);
// A phone gets the path as one back button in the select's row, and no chips.
@@ -340,6 +346,7 @@ export function LibraryCollections({
const items: RowMenuItem[] = [];
if (collection) {
if (collection.role === "admin") {
+ items.push({ label: "Budget…", onSelect: () => setBudgeting(collection) });
items.push({ label: "Move…", icon: "arrow-right", onSelect: () => setMoving(collection) });
items.push({
label: "Delete collection",
@@ -461,6 +468,14 @@ export function LibraryCollections({
)}
+ {budgeting && (
+ setBudgeting(null)}
+ />
+ )}
{moving && (
None:
self._agent = agent
+ async def budget_set(
+ self, body: _ops.CollectionBudgetSetBody | None = None, /, **options: Any
+ ) -> _ops.CollectionBudgetSetOutput:
+ """`collection.budget_set`."""
+ return cast(
+ "_ops.CollectionBudgetSetOutput",
+ await self._agent.call("collection.budget_set", body, **options),
+ )
+
async def create(
self, body: _ops.CollectionCreateBody | None = None, /, **options: Any
) -> _ops.CollectionCreateOutput:
diff --git a/sdk/python/loom/ops.py b/sdk/python/loom/ops.py
index e44224a553..c8bd94fdee 100644
--- a/sdk/python/loom/ops.py
+++ b/sdk/python/loom/ops.py
@@ -100,6 +100,7 @@ class OpSpec:
"code.trace",
"code.verify",
"code.verify_citations",
+ "collection.budget_set",
"collection.create",
"collection.delete",
"collection.list",
@@ -478,6 +479,7 @@ class OpSpec:
"code.trace",
"code.verify",
"code.verify_citations",
+ "collection.budget_set",
"collection.create",
"collection.delete",
"collection.list",
@@ -1527,6 +1529,18 @@ class OpSpec:
False,
True,
),
+ "collection.budget_set": OpSpec(
+ "collection.budget_set",
+ "CollectionBudgetSetInput",
+ "CollectionBudgetSetBody",
+ "CollectionBudgetSetOutput",
+ True,
+ "admin",
+ "experimental",
+ 80,
+ True,
+ False,
+ ),
"collection.create": OpSpec(
"collection.create",
"CollectionCreateInput",
@@ -8123,6 +8137,34 @@ class CodeVerifyCitationsOutput(TypedDict, total=False):
trace_run_id: NotRequired[str]
+class CollectionBudgetSetInput(TypedDict, total=False):
+ "Change only a collection's spend caps and warning destination."
+
+ org: Required[str]
+ namespace: Required[str]
+ daily_cost_cap_usd: NotRequired[Optional[float]]
+ daily_user_cost_cap_usd: NotRequired[Optional[float]]
+ budget_alert_inbox: NotRequired[Optional[str]]
+
+
+class CollectionBudgetSetBody(TypedDict, total=False):
+ "Change only a collection's spend caps and warning destination."
+
+ org: NotRequired[str]
+ namespace: NotRequired[str]
+ daily_cost_cap_usd: NotRequired[Optional[float]]
+ daily_user_cost_cap_usd: NotRequired[Optional[float]]
+ budget_alert_inbox: NotRequired[Optional[str]]
+
+
+class CollectionBudgetSetOutput(TypedDict, total=False):
+ namespace: Required[str]
+ changed: Required[bool]
+ daily_cost_cap_usd: Required[float]
+ daily_user_cost_cap_usd: Required[float]
+ budget_alert_inbox: Required[str]
+
+
class CollectionCreateInput(TypedDict, total=False):
"Create a collection: a namespace read and written only through grants."
diff --git a/sdk/typescript/src/generated/ops.ts b/sdk/typescript/src/generated/ops.ts
index ff302c5c8a..e67a83e242 100644
--- a/sdk/typescript/src/generated/ops.ts
+++ b/sdk/typescript/src/generated/ops.ts
@@ -1889,6 +1889,25 @@ export interface CodeVerifyCitationsOutput {
trace_run_id?: string;
}
+export interface CollectionBudgetSetInput {
+ org: string;
+ namespace: string;
+ /** Collection cap in USD per rolling 24 hours; 0 inherits the server default, omit keeps it. */
+ daily_cost_cap_usd?: number | null;
+ /** Named-user cap in USD per rolling 24 hours; 0 inherits the server default, omit keeps it. */
+ daily_user_cost_cap_usd?: number | null;
+ /** An existing task inbox owned by this collection; '' disables warnings, omit keeps it. */
+ budget_alert_inbox?: string | null;
+}
+
+export interface CollectionBudgetSetOutput {
+ namespace: string;
+ changed: boolean;
+ daily_cost_cap_usd: number;
+ daily_user_cost_cap_usd: number;
+ budget_alert_inbox: string;
+}
+
export interface CollectionCreateInput {
org: string;
/** The collection's name, also its namespace ('col-' then lowercase letters, digits and '-'), ignored with `derive_name`. */
@@ -10533,6 +10552,7 @@ export type OpName =
| "code.trace"
| "code.verify"
| "code.verify_citations"
+ | "collection.budget_set"
| "collection.create"
| "collection.delete"
| "collection.list"
@@ -10911,6 +10931,7 @@ export interface OpMap {
"code.trace": { input: CodeTraceInput; output: CodeTraceOutput };
"code.verify": { input: CodeVerifyInput; output: CodeVerifyOutput };
"code.verify_citations": { input: CodeVerifyCitationsInput; output: CodeVerifyCitationsOutput };
+ "collection.budget_set": { input: CollectionBudgetSetInput; output: CollectionBudgetSetOutput };
"collection.create": { input: CollectionCreateInput; output: CollectionCreateOutput };
"collection.delete": { input: CollectionDeleteInput; output: CollectionDeleteOutput };
"collection.list": { input: CollectionListInput; output: CollectionListOutput };
@@ -11289,6 +11310,7 @@ export const OPS: readonly OpSpec[] = [
{ name: "code.trace", group: "code", method: "trace", idempotent: true, role: "viewer", maturity: "stable", budgetP99Ms: 800, audit: false, readOnly: true },
{ name: "code.verify", group: "code", method: "verify", idempotent: true, role: "viewer", maturity: "stable", budgetP99Ms: 1500, audit: false, readOnly: true },
{ name: "code.verify_citations", group: "code", method: "verifyCitations", idempotent: true, role: "viewer", maturity: "experimental", budgetP99Ms: 1500, audit: false, readOnly: true },
+ { name: "collection.budget_set", group: "collection", method: "budgetSet", idempotent: true, role: "admin", maturity: "experimental", budgetP99Ms: 80, audit: true, readOnly: false },
{ name: "collection.create", group: "collection", method: "create", idempotent: true, role: "viewer", maturity: "experimental", budgetP99Ms: 80, audit: true, readOnly: false },
{ name: "collection.delete", group: "collection", method: "delete", idempotent: true, role: "admin", maturity: "experimental", budgetP99Ms: 2000, audit: true, readOnly: false },
{ name: "collection.list", group: "collection", method: "list", idempotent: true, role: "viewer", maturity: "experimental", budgetP99Ms: 80, audit: false, readOnly: true },
@@ -11609,4 +11631,4 @@ export const OP_BY_NAME: Readonly> = Object.fromEntries(
OPS.map((o) => [o.name, o]),
) as Readonly>;
-export const GENERATED_OP_COUNT = 375;
+export const GENERATED_OP_COUNT = 376;
diff --git a/server/identity/api/models_collections.py b/server/identity/api/models_collections.py
index fe28cf2a9f..7facf4686b 100644
--- a/server/identity/api/models_collections.py
+++ b/server/identity/api/models_collections.py
@@ -101,6 +101,41 @@ class CollectionMoveOutput(BaseModel):
moved: bool # False when it already sat there
+class CollectionBudgetSetInput(BaseModel):
+ """Change only a collection's spend caps and warning destination."""
+
+ org: str
+ namespace: str
+ daily_cost_cap_usd: float | None = Field(
+ default=None,
+ ge=0,
+ allow_inf_nan=False,
+ description="Collection cap in USD per rolling 24 hours; "
+ "0 inherits the server default, omit keeps it.",
+ )
+ daily_user_cost_cap_usd: float | None = Field(
+ default=None,
+ ge=0,
+ allow_inf_nan=False,
+ description="Named-user cap in USD per rolling 24 hours; "
+ "0 inherits the server default, omit keeps it.",
+ )
+ budget_alert_inbox: str | None = Field(
+ default=None,
+ max_length=128,
+ description="An existing task inbox owned by this collection; "
+ "'' disables warnings, omit keeps it.",
+ )
+
+
+class CollectionBudgetSetOutput(BaseModel):
+ namespace: str
+ changed: bool
+ daily_cost_cap_usd: float
+ daily_user_cost_cap_usd: float
+ budget_alert_inbox: str
+
+
class CollectionListInput(BaseModel):
"""List the collections the caller can read, by name."""
diff --git a/server/identity/api/ops_collections.py b/server/identity/api/ops_collections.py
index 5692574caa..88459f4091 100644
--- a/server/identity/api/ops_collections.py
+++ b/server/identity/api/ops_collections.py
@@ -3,6 +3,8 @@
from __future__ import annotations
from server.identity.api.models_collections import (
+ CollectionBudgetSetInput,
+ CollectionBudgetSetOutput,
CollectionCreateInput,
CollectionCreateOutput,
CollectionDeleteInput,
@@ -12,6 +14,7 @@
CollectionMoveInput,
CollectionMoveOutput,
)
+from server.identity.app.collection_budgets import handle_collection_budget_set
from server.identity.app.collections import (
create_audit_namespace,
create_audit_subject,
@@ -53,6 +56,17 @@
audit=True,
)
+collection_budget_set = Operation(
+ name="collection.budget_set",
+ maturity="experimental",
+ input_model=CollectionBudgetSetInput,
+ output_model=CollectionBudgetSetOutput,
+ handler=handle_collection_budget_set,
+ idempotent=True,
+ required_role=Role.ADMIN,
+ audit=True,
+)
+
collection_list = Operation(
name="collection.list",
maturity="experimental",
@@ -80,6 +94,7 @@
)
OPERATIONS: list[Operation] = [
+ collection_budget_set,
collection_create,
collection_move,
collection_list,
diff --git a/server/identity/app/collection_budgets.py b/server/identity/app/collection_budgets.py
new file mode 100644
index 0000000000..ab018bd324
--- /dev/null
+++ b/server/identity/app/collection_budgets.py
@@ -0,0 +1,58 @@
+"""Spend policy for grant-authorized collections, stored in their directory row."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from server.auth import sharing
+from server.auth.authz import identity_write
+from server.auth.grant_claims import account_change
+from server.core.ch import get_client, own_write_reads
+from server.core.datetimes import naive_utc_now_seconds
+from server.core.errors import ValidationError
+from server.identity.api.models_collections import (
+ CollectionBudgetSetInput,
+ CollectionBudgetSetOutput,
+)
+from server.identity.store import collections as collections_repo
+from server.identity.store import namespaces as namespaces_repo
+from server.tasks.app.budget_notifications import inbox_owned_by
+
+_FIELDS = ("daily_cost_cap_usd", "daily_user_cost_cap_usd", "budget_alert_inbox")
+
+
+def _patch(input: CollectionBudgetSetInput) -> dict[str, Any]:
+ patch = {key: getattr(input, key) for key in _FIELDS if key in input.model_fields_set}
+ if not patch or any(value is None for value in patch.values()):
+ raise ValidationError("supply at least one budget field; null does not change a policy")
+ return patch
+
+
+async def handle_collection_budget_set(
+ input: CollectionBudgetSetInput,
+) -> CollectionBudgetSetOutput:
+ """The transport checks ADMIN on this collection before its policy is read or changed."""
+ org, namespace = input.org, input.namespace
+ patch = _patch(input)
+ if not sharing.is_collection(namespace) or sharing.is_personal(namespace):
+ raise ValidationError("budget settings require a non-personal collection")
+ ch = get_client()
+ async with account_change(org, namespace):
+ with own_write_reads():
+ row = await namespaces_repo.fetch_row(org, namespace, ch=ch)
+ live = await collections_repo.fetch(org, namespace, ch=ch)
+ if not row or row.get("kind") != "collection" or not row.get("active") or not live:
+ raise ValidationError("budget settings require an active collection")
+ inbox = patch.get("budget_alert_inbox")
+ if inbox and not await inbox_owned_by(org, namespace, inbox):
+ raise ValidationError(
+ "budget_alert_inbox must name an existing task inbox owned by this collection"
+ )
+ changed = any(row.get(key) != value for key, value in patch.items())
+ if changed:
+ row = {**row, **patch, "updated_at": max(naive_utc_now_seconds(), row["updated_at"])}
+ with identity_write():
+ await ch.insert("loom.namespaces", [row])
+ return CollectionBudgetSetOutput(
+ namespace=namespace, changed=changed, **{key: row[key] for key in _FIELDS}
+ )
diff --git a/server/operations/reach_manifest.py b/server/operations/reach_manifest.py
index 0ebff31d12..66ab1c8286 100644
--- a/server/operations/reach_manifest.py
+++ b/server/operations/reach_manifest.py
@@ -123,6 +123,7 @@
"code.trace": ("sdk_method",),
"code.verify": ("sdk_method",),
"code.verify_citations": ("sdk_method",),
+ "collection.budget_set": ("dashboard",),
"collection.create": ("dashboard",),
"collection.delete": ("dashboard",),
"collection.list": (
diff --git a/server/settings/catalog.py b/server/settings/catalog.py
index 73fa1f56cc..c3728763be 100644
--- a/server/settings/catalog.py
+++ b/server/settings/catalog.py
@@ -6255,6 +6255,7 @@ class TrackerSettings(BaseModel):
# (batched), items by number, one name lookup per qualified name
# (<=8 gathered); the optional mirror leg is capped at 20 calls / 5 s
"code.verify_citations": 1500,
+ "collection.budget_set": 80,
"collection.create": 80,
# It runs the purging erasure inline, as `erasure.request` does.
"collection.delete": 2000,
diff --git a/tests/integration/test_knowledge_sharing.py b/tests/integration/test_knowledge_sharing.py
index a93dfcb4b8..b91ffe4490 100644
--- a/tests/integration/test_knowledge_sharing.py
+++ b/tests/integration/test_knowledge_sharing.py
@@ -1109,3 +1109,67 @@ def test_a_document_says_which_agent_and_session_wrote_it_and_what_it_is(gw: Gat
{"namespace": col, "source_uri": "x", "content": "y", "source_class": "observed"},
)
assert refused.status_code == 422, "a body only declares a downgrade"
+
+
+def test_only_collection_admins_change_its_spend_policy_and_keep_other_settings(
+ gw: Gateway,
+) -> None:
+ tag = uuid.uuid4().hex[:8]
+ collection = _collection(gw, "alice", f"col-budget-{tag}")
+ foreign = _collection(gw, "alice", f"col-foreign-{tag}")
+ for user, role in (("bob", "viewer"), ("carol", "writer")):
+ gw.ok(
+ "alice",
+ "grants.create",
+ {"namespace": collection, "subject": f"user:{user}", "role": role},
+ )
+ before = gw.ok("alice", "namespace.get", {"namespace": collection})
+ original = {
+ field: before[field]
+ for field in ("daily_cost_cap_usd", "daily_user_cost_cap_usd", "budget_alert_inbox")
+ }
+ patch = {"namespace": collection, "daily_cost_cap_usd": 0.25, "daily_user_cost_cap_usd": 0.125}
+ for user in ("bob", "carol", "dan"):
+ assert gw.call(user, "collection.budget_set", patch).status_code == 403
+ other_org = httpx.post(
+ f"{gw.base}/v1/collection.budget_set",
+ json={"org": gw.org, **patch},
+ headers={"Authorization": f"Bearer {end_user_issuer.mint(gw.org + '-other', 'alice')}"},
+ timeout=60,
+ )
+ assert other_org.status_code == 403
+ own_inbox, foreign_inbox = f"budget-{tag}", f"other-{tag}"
+ for namespace, inbox in ((collection, own_inbox), (foreign, foreign_inbox)):
+ gw.ok(
+ "alice", "inbox.register", {"namespace": namespace, "inbox": inbox, "owner_agent": "-"}
+ )
+ rejected = gw.call(
+ "alice", "collection.budget_set", {**patch, "budget_alert_inbox": foreign_inbox}
+ )
+ assert rejected.status_code == 422 and "owned by this collection" in rejected.text
+ assert gw.ok("alice", "namespace.get", {"namespace": collection}) == before
+ changed = gw.ok("alice", "collection.budget_set", {**patch, "budget_alert_inbox": own_inbox})
+ assert changed["changed"] and changed["daily_cost_cap_usd"] == 0.25
+ after = gw.ok("alice", "namespace.get", {"namespace": collection})
+ expected = {
+ **before,
+ "daily_cost_cap_usd": 0.25,
+ "daily_user_cost_cap_usd": 0.125,
+ "budget_alert_inbox": own_inbox,
+ }
+ assert {key: value for key, value in after.items() if key != "updated_at"} == {
+ key: value for key, value in expected.items() if key != "updated_at"
+ }
+ status = gw.ok("alice", "cost.budget_status", {"namespace": collection})
+ assert status["cap_source"] == "namespace" and status["cap_usd"] == 0.25
+ gw.ok("alice", "collection.budget_set", {"namespace": collection, **original})
+ restored = gw.ok("alice", "namespace.get", {"namespace": collection})
+ assert {key: value for key, value in restored.items() if key != "updated_at"} == {
+ key: value for key, value in before.items() if key != "updated_at"
+ }
+ wrong_route = gw.call(
+ "alice",
+ "namespace.register",
+ {"namespace": collection, "owner_email": "user:alice", "daily_cost_cap_usd": 1},
+ )
+ assert wrong_route.status_code == 422 and "collection operations only" in wrong_route.text
diff --git a/tests/unit/snapshots/sdk_public_api.json b/tests/unit/snapshots/sdk_public_api.json
index 48adad0e03..4bd91bf90e 100644
--- a/tests/unit/snapshots/sdk_public_api.json
+++ b/tests/unit/snapshots/sdk_public_api.json
@@ -516,6 +516,10 @@
"collection": {
"class": "CollectionOps",
"methods": {
+ "budget_set": [
+ "body",
+ "options"
+ ],
"create": [
"body",
"options"
diff --git a/tests/unit/test_collection_budgets.py b/tests/unit/test_collection_budgets.py
new file mode 100644
index 0000000000..339f275b9b
--- /dev/null
+++ b/tests/unit/test_collection_budgets.py
@@ -0,0 +1,235 @@
+"""A collection's admins can change its spend policy without rewriting its identity."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Any
+
+import pydantic
+import pytest
+
+from server.core.errors import ValidationError
+from server.identity.api.models import NamespaceRegisterInput
+from server.identity.api.models_collections import CollectionBudgetSetInput
+from server.identity.app import collection_budgets as h
+from server.identity.app.namespace import handle_namespace_register
+from server.observability import budget
+from server.operations.base import Role
+from server.operations.registry import ALL_OPERATIONS
+
+
+def test_a_collection_has_an_audited_admin_budget_operation() -> None:
+ ops = {op.name: op for op in ALL_OPERATIONS}
+ assert "collection.budget_set" in ops
+ op = ops["collection.budget_set"]
+ assert op.required_role == Role.ADMIN and op.audit and op.idempotent
+ assert not op.skip_namespace_authz and not op.deployment_scoped
+
+
+class Store:
+ def __init__(self) -> None:
+ self.held = False
+ self.live = True
+ self.inbox_checks: list[tuple[str, str, str]] = []
+ self.writes: list[dict[str, Any]] = []
+ self.row: dict[str, Any] | None = {
+ "org": "o",
+ "namespace": "col-a",
+ "kind": "collection",
+ "active": True,
+ "daily_cost_cap_usd": 2.0,
+ "daily_user_cost_cap_usd": 1.0,
+ "budget_alert_inbox": "",
+ "updated_at": datetime(2026, 1, 2),
+ "created_at": datetime(2025, 1, 1),
+ "classification": "restricted",
+ "visibility": "private",
+ "title": "Plans",
+ "tags": ["a"],
+ "owner_email": "owner",
+ "password_hash": "hash",
+ "capture_generation_io": False,
+ "future_column": {"must": "remain"},
+ }
+
+ async def insert(self, table: str, rows: list[dict[str, Any]]) -> None:
+ assert self.held and table == "loom.namespaces"
+ [row] = rows
+ self.writes.append(dict(row))
+ self.row = dict(row)
+
+ async def query_one(self, sql: str, params: dict[str, Any]) -> dict[str, Any]:
+ assert params["org"] == "o" and params["ns"] == "col-a"
+ if "FROM loom.namespaces" in sql:
+ return dict(self.row or {})
+ # Offline cost rows prove the existing guard consumes the new stored cap.
+ return {"spent": 0.5, "own": 0, "user_spent": 0.2, "user_own": 0}
+
+
+@pytest.fixture
+def store(monkeypatch: pytest.MonkeyPatch) -> Store:
+ s = Store()
+
+ @asynccontextmanager
+ async def held(org: str, ns: str) -> Any:
+ assert (org, ns) == ("o", "col-a") and not s.held
+ s.held = True
+ try:
+ yield
+ finally:
+ s.held = False
+
+ async def fetch(org: str, ns: str, **kw: Any) -> dict[str, Any] | None:
+ assert s.held and (org, ns) == ("o", "col-a")
+ return dict(s.row) if s.row else None
+
+ async def live(org: str, ns: str, **kw: Any) -> dict[str, Any] | None:
+ assert s.held and (org, ns) == ("o", "col-a")
+ return {"namespace": ns} if s.live else None
+
+ async def inbox(org: str, ns: str, name: str) -> bool:
+ s.inbox_checks.append((org, ns, name))
+ return name == "owned"
+
+ monkeypatch.setattr(h, "account_change", held)
+ monkeypatch.setattr(h.namespaces_repo, "fetch_row", fetch)
+ monkeypatch.setattr(h.collections_repo, "fetch", live)
+ monkeypatch.setattr(h, "inbox_owned_by", inbox)
+ monkeypatch.setattr(h, "get_client", lambda: s)
+ monkeypatch.setattr(h, "naive_utc_now_seconds", lambda: datetime(2026, 1, 1))
+ return s
+
+
+def request(**fields: Any) -> CollectionBudgetSetInput:
+ return CollectionBudgetSetInput(org="o", namespace="col-a", **fields)
+
+
+async def test_patch_preserves_every_unrelated_column_and_never_moves_the_timestamp_back(
+ store: Store,
+) -> None:
+ before = dict(store.row or {})
+ out = await h.handle_collection_budget_set(request(daily_cost_cap_usd=0.25))
+ assert out.changed and out.daily_cost_cap_usd == 0.25
+ assert out.daily_user_cost_cap_usd == 1.0 and out.budget_alert_inbox == ""
+ assert store.row == {**before, "daily_cost_cap_usd": 0.25}
+ assert not store.held and len(store.writes) == 1
+
+
+async def test_user_cap_and_owned_inbox_can_be_changed_then_restored(store: Store) -> None:
+ before = dict(store.row or {})
+ changed = await h.handle_collection_budget_set(
+ request(daily_user_cost_cap_usd=0.125, budget_alert_inbox="owned")
+ )
+ assert changed.daily_cost_cap_usd == 2.0 and changed.daily_user_cost_cap_usd == 0.125
+ assert store.inbox_checks == [("o", "col-a", "owned")]
+ await h.handle_collection_budget_set(request(daily_user_cost_cap_usd=1, budget_alert_inbox=""))
+ assert store.row == before
+
+
+async def test_an_identical_patch_does_not_rewrite_the_directory(store: Store) -> None:
+ out = await h.handle_collection_budget_set(request(daily_cost_cap_usd=2))
+ assert not out.changed and not store.writes
+
+
+async def test_foreign_or_missing_inbox_is_refused_without_changing_policy(store: Store) -> None:
+ before = dict(store.row or {})
+ with pytest.raises(ValidationError, match="owned by this collection"):
+ await h.handle_collection_budget_set(
+ request(daily_cost_cap_usd=0.25, budget_alert_inbox="foreign")
+ )
+ assert store.inbox_checks == [("o", "col-a", "foreign")]
+ assert not store.writes and store.row == before
+
+
+@pytest.mark.parametrize("state", ["missing", "inactive", "wrong_kind", "retired_tree"])
+async def test_missing_inactive_or_retired_collections_are_not_resurrected(
+ store: Store, state: str
+) -> None:
+ if state == "missing":
+ store.row = None
+ elif state == "retired_tree":
+ store.live = False
+ else:
+ assert store.row
+ store.row["active" if state == "inactive" else "kind"] = (
+ False if state == "inactive" else "agent"
+ )
+ with pytest.raises(ValidationError, match="active collection"):
+ await h.handle_collection_budget_set(request(daily_cost_cap_usd=0.25))
+ assert not store.writes
+
+
+@pytest.mark.parametrize("ns", ["account", "col-me-12345678"])
+async def test_account_and_personal_names_cannot_enter_collection_policy_writes(
+ store: Store, ns: str
+) -> None:
+ with pytest.raises(ValidationError, match="non-personal collection"):
+ await h.handle_collection_budget_set(
+ CollectionBudgetSetInput(org="o", namespace=ns, daily_cost_cap_usd=1)
+ )
+ assert not store.writes
+
+
+@pytest.mark.parametrize(
+ "patch",
+ [
+ {},
+ {"daily_cost_cap_usd": None},
+ {"daily_user_cost_cap_usd": None},
+ {"budget_alert_inbox": None},
+ ],
+)
+async def test_empty_and_null_patches_do_not_silently_clear_policy(
+ store: Store, patch: dict[str, Any]
+) -> None:
+ with pytest.raises(ValidationError, match="at least one budget field"):
+ await h.handle_collection_budget_set(request(**patch))
+ assert not store.writes
+
+
+@pytest.mark.parametrize("field", ["daily_cost_cap_usd", "daily_user_cost_cap_usd"])
+@pytest.mark.parametrize("value", [-1, float("inf"), float("-inf"), float("nan")])
+def test_caps_are_finite_nonnegative_dollar_values(field: str, value: float) -> None:
+ with pytest.raises(pydantic.ValidationError):
+ request(**{field: value})
+
+
+async def test_zero_restores_existing_default_semantics_and_positive_caps_reach_the_guard(
+ store: Store, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from server.settings import settings
+
+ monkeypatch.setattr(settings, "default_daily_cost_cap_usd", 3)
+ monkeypatch.setattr(settings, "default_daily_user_cost_cap_usd", 2)
+ await h.handle_collection_budget_set(request(daily_cost_cap_usd=0, daily_user_cost_cap_usd=0))
+ snapshot = await budget.budget_snapshot("o", "col-a", user_id="named", ch=store)
+ assert (snapshot.cap, snapshot.cap_source, snapshot.user_cap, snapshot.user_cap_source) == (
+ 3,
+ "global",
+ 2,
+ "global_user",
+ )
+ assert not snapshot.over("named", "", 1)
+ await h.handle_collection_budget_set(
+ request(daily_cost_cap_usd=0.25, daily_user_cost_cap_usd=0.125)
+ )
+ snapshot = await budget.budget_snapshot("o", "col-a", user_id="named", ch=store)
+ assert snapshot.over("named", "", 1)
+ assert (snapshot.cap_source, snapshot.user_cap_source) == ("namespace", "namespace_user")
+
+
+async def test_namespace_register_still_refuses_the_original_collection_route(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ monkeypatch.setattr("server.identity.app.namespace.resolve_subject", lambda: "owner")
+ with pytest.raises(ValidationError, match="collection operations only"):
+ await handle_namespace_register(
+ NamespaceRegisterInput(
+ org="o",
+ namespace="col-a",
+ owner_email="owner",
+ daily_cost_cap_usd=0.05,
+ daily_user_cost_cap_usd=0.025,
+ )
+ )
From 6e6048b06c34aa7313af9d18c59ad69c0d7f9cb4 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 18:32:00 +0000
Subject: [PATCH 03/11] Budget controls explain the required collection role
Keep the unavailable action discoverable and declare the existing inbox ownership check in the scope contract.
Signed-off-by: zlareb1
---
.../src/flows/CollectionBudgetDialog.test.tsx | 20 +++++++++++++++++++
.../src/views/LibraryCollections.test.tsx | 7 +++++--
frontend/src/views/LibraryCollections.tsx | 9 ++++++++-
tests/unit/test_op_scope_fields.py | 3 +++
4 files changed, 36 insertions(+), 3 deletions(-)
diff --git a/frontend/src/flows/CollectionBudgetDialog.test.tsx b/frontend/src/flows/CollectionBudgetDialog.test.tsx
index 911547f354..b4d4edbc49 100644
--- a/frontend/src/flows/CollectionBudgetDialog.test.tsx
+++ b/frontend/src/flows/CollectionBudgetDialog.test.tsx
@@ -121,3 +121,23 @@ it("an old save cannot close a later collection dialog or discard its draft", as
expect(screen.getByLabelText("Daily cost cap (USD)")).toHaveValue(7);
expect(toast).not.toHaveBeenCalled();
});
+
+it.each(["viewer", "writer"] as const)(
+ "the unavailable Budget action remains keyboard reachable for a %s without reading or writing policy",
+ async (role) => {
+ const c = entry("col-a", { role });
+ render();
+ const trigger = screen.getByRole("button", { name: "Actions for col-a" });
+ trigger.focus();
+ await userEvent.keyboard("{ArrowDown}");
+ const budget = await screen.findByRole("menuitem", { name: "Budget…" });
+ await waitFor(() => expect(budget).toHaveFocus());
+ expect(budget).toHaveAttribute("aria-disabled", "true");
+ expect(budget).toHaveAccessibleDescription("Needs admin on col-a. An admin of it can grant that.");
+ await userEvent.keyboard("{Enter} ");
+ await userEvent.click(budget);
+ expect(screen.queryByRole("dialog")).not.toBeInTheDocument();
+ expect(api.getNamespace).not.toHaveBeenCalled();
+ expect(api.setCollectionBudget).not.toHaveBeenCalled();
+ },
+);
diff --git a/frontend/src/views/LibraryCollections.test.tsx b/frontend/src/views/LibraryCollections.test.tsx
index 263a05f4bd..47c498e1b2 100644
--- a/frontend/src/views/LibraryCollections.test.tsx
+++ b/frontend/src/views/LibraryCollections.test.tsx
@@ -141,9 +141,12 @@ describe("LibraryCollections", () => {
expect(screen.getByRole("button", { name: "Actions for col-q3" })).toBeInTheDocument();
});
- it("gives a viewer no menu: its members are behind See who in the header", async () => {
+ it("gives a viewer the unavailable Budget action without Move or Delete", async () => {
render( undefined} />);
- expect(screen.queryByRole("button", { name: "Actions for col-plans" })).not.toBeInTheDocument();
+ await userEvent.click(screen.getByRole("button", { name: "Actions for col-plans" }));
+ expect(await screen.findByRole("menuitem", { name: "Budget…" })).toHaveAttribute("aria-disabled", "true");
+ expect(screen.queryByRole("menuitem", { name: "Move…" })).not.toBeInTheDocument();
+ expect(screen.queryByRole("menuitem", { name: "Delete collection" })).not.toBeInTheDocument();
});
it("on a phone shows the path as one back button and leaves the collections inside to the select", () => {
diff --git a/frontend/src/views/LibraryCollections.tsx b/frontend/src/views/LibraryCollections.tsx
index 1c4de520f5..6b26675a77 100644
--- a/frontend/src/views/LibraryCollections.tsx
+++ b/frontend/src/views/LibraryCollections.tsx
@@ -30,6 +30,7 @@ import { PHONE_QUERY, useMedia } from "../lib/useMedia";
import { PLACE_PICKER_LABEL } from "../lib/useTreeFocusHandoff";
import { invalidateSharedCollections, onCollectionsChanged } from "../lib/collectionPlaces";
import { ALL_DOCUMENTS } from "../lib/libraryPlace";
+import { needsRole } from "../lib/namespaceRole";
/** The select's value for the namespace picked in the header: an item cannot carry "". */
const NAMESPACE_SHELF = "__namespace__";
@@ -345,8 +346,14 @@ export function LibraryCollections({
const collection = current && !current.personal ? current : null;
const items: RowMenuItem[] = [];
if (collection) {
+ items.push({
+ label: "Budget…",
+ reason: collection.role === "admin" ? null : needsRole("admin", collection.namespace),
+ onSelect: () => {
+ if (collection.role === "admin") setBudgeting(collection);
+ },
+ });
if (collection.role === "admin") {
- items.push({ label: "Budget…", onSelect: () => setBudgeting(collection) });
items.push({ label: "Move…", icon: "arrow-right", onSelect: () => setMoving(collection) });
items.push({
label: "Delete collection",
diff --git a/tests/unit/test_op_scope_fields.py b/tests/unit/test_op_scope_fields.py
index 338487d2c9..383b80aae5 100644
--- a/tests/unit/test_op_scope_fields.py
+++ b/tests/unit/test_op_scope_fields.py
@@ -39,6 +39,9 @@
# (op, field) -> the function that authorizes the field's value.
AUTHORIZED: dict[tuple[str, str], str] = {
+ ("collection.budget_set", "budget_alert_inbox"): (
+ "server.tasks.app.budget_notifications.inbox_owned_by"
+ ),
("namespace.register", "budget_alert_inbox"): (
"server.tasks.app.budget_notifications.inbox_owned_by"
),
From 6e6dfcd0624d8d11fa4e141477543d245b459f11 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 18:38:22 +0000
Subject: [PATCH 04/11] Budget policy read errors describe a read failure
Loading a policy cannot have committed a save, so reserve write uncertainty for failed updates.
Signed-off-by: zlareb1
---
frontend/src/flows/CollectionBudgetDialog.test.tsx | 6 ++++--
frontend/src/flows/CollectionBudgetDialog.tsx | 2 +-
2 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/frontend/src/flows/CollectionBudgetDialog.test.tsx b/frontend/src/flows/CollectionBudgetDialog.test.tsx
index b4d4edbc49..95ca59d7a0 100644
--- a/frontend/src/flows/CollectionBudgetDialog.test.tsx
+++ b/frontend/src/flows/CollectionBudgetDialog.test.tsx
@@ -52,10 +52,12 @@ it("reads the collection policy and saves only changed budget fields to that col
});
it("keeps a failed save open and sends no write before its policy read succeeds", async () => {
- vi.mocked(api.getNamespace).mockRejectedValueOnce(new Error("Read unavailable"));
+ vi.mocked(api.getNamespace).mockRejectedValueOnce(new TypeError("Failed to fetch"));
const close = vi.fn();
render();
- await screen.findByRole("alert");
+ const error = await screen.findByRole("alert");
+ expect(error).toHaveTextContent(/connection|reach|network/i);
+ expect(error).not.toHaveTextContent(/saved|committed|re-check|check before/i);
expect(screen.getByRole("button", { name: "Save budget" })).toBeDisabled();
expect(api.setCollectionBudget).not.toHaveBeenCalled();
expect(close).not.toHaveBeenCalled();
diff --git a/frontend/src/flows/CollectionBudgetDialog.tsx b/frontend/src/flows/CollectionBudgetDialog.tsx
index 2879223ad2..9df56b8b61 100644
--- a/frontend/src/flows/CollectionBudgetDialog.tsx
+++ b/frontend/src/flows/CollectionBudgetDialog.tsx
@@ -44,7 +44,7 @@ export function CollectionBudgetDialog({
setUserCap(String(policy.daily_user_cost_cap_usd));
setInbox(policy.budget_alert_inbox);
} catch (e) {
- if (live()) setError(humanizeError(e));
+ if (live()) setError(humanizeError(e, { read: true }));
}
},
[org, collection.namespace],
From eeb4af7cc408fc97f7933d009e448067b0e3cf00 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 18:55:46 +0000
Subject: [PATCH 05/11] Collection budgets declare their full-row namespace
writer
Keep classification and unknown columns through the existing full-row read. Retain failed read-count assertions and include request details for diagnosis.
Signed-off-by: zlareb1
---
frontend/src/views/LibraryCollections.test.tsx | 16 +++++++++++++---
...t_namespaces_writers_mirror_classification.py | 1 +
2 files changed, 14 insertions(+), 3 deletions(-)
diff --git a/frontend/src/views/LibraryCollections.test.tsx b/frontend/src/views/LibraryCollections.test.tsx
index 47c498e1b2..8082e82105 100644
--- a/frontend/src/views/LibraryCollections.test.tsx
+++ b/frontend/src/views/LibraryCollections.test.tsx
@@ -1193,6 +1193,16 @@ describe("the Library on a collection", () => {
});
describe("a create's answer, and the reads it starts", () => {
+ const readDetails = (from: number) =>
+ JSON.stringify(
+ api.listCollections.mock.calls.slice(from).map(([org, options]) => ({
+ org,
+ cursor: options?.cursor,
+ includeDocumentCounts: options?.includeDocumentCounts,
+ aborted: options?.signal?.aborted,
+ })),
+ );
+
it("still opens it when a resize took the tree away", async () => {
const narrow = resizable();
const answer = await createInTree();
@@ -1408,7 +1418,7 @@ describe("the Library on a collection", () => {
const reads = api.listCollections.mock.calls.length;
await answer(q4);
await settle();
- expect(api.listCollections.mock.calls.length - reads).toBe(1);
+ expect(api.listCollections.mock.calls.length - reads, readDetails(reads)).toBe(1);
expect(new URLSearchParams(location.search).get("collection")).toBe("col-q4");
});
@@ -1429,7 +1439,7 @@ describe("the Library on a collection", () => {
const reads = api.listCollections.mock.calls.length;
await act(async () => answer(q4));
await settle();
- expect(api.listCollections.mock.calls.length - reads).toBe(1);
+ expect(api.listCollections.mock.calls.length - reads, readDetails(reads)).toBe(1);
expect(new URLSearchParams(location.search).get("collection")).toBe("col-q4");
});
@@ -1487,7 +1497,7 @@ describe("the Library on a collection", () => {
fireEvent.click(screen.getByRole("button", { name: "Create" }));
await settle();
expect(new URLSearchParams(location.search).get("collection")).toBe("col-q5");
- expect(api.listCollections.mock.calls.length - reads).toBe(1);
+ expect(api.listCollections.mock.calls.length - reads, readDetails(reads)).toBe(1);
});
it("moves nothing once the page shows another org", async () => {
diff --git a/tests/unit/test_namespaces_writers_mirror_classification.py b/tests/unit/test_namespaces_writers_mirror_classification.py
index c37854a720..548bfed05d 100644
--- a/tests/unit/test_namespaces_writers_mirror_classification.py
+++ b/tests/unit/test_namespaces_writers_mirror_classification.py
@@ -88,6 +88,7 @@ def test_every_literal_namespaces_insert_is_a_known_writer() -> None:
"server/identity/app/conversation_logging.py", # SELECT * new version: set_logging
"server/identity/app/claim_release.py", # SELECT * new version: release
"server/identity/app/collections.py", # registry_row + full-row copy (title)
+ "server/identity/app/collection_budgets.py", # SELECT * via namespaces_repo.fetch_row
}
found = set()
for path in (ROOT / "server").rglob("*.py"):
From 806cf111410ce6f96f1db086de992453775c1b31 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 19:07:30 +0000
Subject: [PATCH 06/11] Superseded collection reads stop before starting
requests
Signed-off-by: zlareb1
---
frontend/src/views/LibraryCollections.test.tsx | 16 ++++++++++++++++
frontend/src/views/LibraryCollections.tsx | 2 ++
2 files changed, 18 insertions(+)
diff --git a/frontend/src/views/LibraryCollections.test.tsx b/frontend/src/views/LibraryCollections.test.tsx
index 8082e82105..6915d836ee 100644
--- a/frontend/src/views/LibraryCollections.test.tsx
+++ b/frontend/src/views/LibraryCollections.test.tsx
@@ -215,6 +215,22 @@ describe("useReadableCollections", () => {
return {c.rows === null ? "reading" : c.rows.map((r) => r.namespace).join(",")}
;
}
+ it("starts only the latest collection read when earlier effects were replaced before running", async () => {
+ let latest: ReadableCollections | null = null;
+ function Holder() {
+ latest = useReadableCollections("acme");
+ return null;
+ }
+ api.listCollections.mockResolvedValue({ collections: [entry("col-a")], next_cursor: null });
+ render();
+ // The deferred reads have not run yet: each reload supersedes the one before it.
+ act(() => latest?.reload());
+ act(() => latest?.reload());
+ await settle();
+ expect(api.listCollections).toHaveBeenCalledTimes(1);
+ expect(api.listCollections.mock.calls[0][1].signal.aborted).toBe(false);
+ });
+
it("requests document counts with every collection page", async () => {
api.listCollections
.mockResolvedValueOnce({ collections: [entry("col-a")], next_cursor: "col-a" })
diff --git a/frontend/src/views/LibraryCollections.tsx b/frontend/src/views/LibraryCollections.tsx
index 6b26675a77..73791616bf 100644
--- a/frontend/src/views/LibraryCollections.tsx
+++ b/frontend/src/views/LibraryCollections.tsx
@@ -156,6 +156,8 @@ export function useReadableCollections(org: string, showing: string | null = nul
const hold = answered && showing !== null && answer.rows.some((c) => c.namespace === showing) ? showing : "";
useAbortableEffect(
(signal, live) => {
+ // A reload can replace this effect before its deferred callback runs.
+ if (!live()) return;
setError(null);
void (async () => {
for (let attempt = 0; ; attempt++) {
From da10527d0e3106ad795c10add92ccaa720d6f156 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 19:19:00 +0000
Subject: [PATCH 07/11] Collection creation invalidates reads before opening
the result
Signed-off-by: zlareb1
---
frontend/src/flows/CreateCollectionDialog.tsx | 4 ++-
.../src/views/LibraryCollections.test.tsx | 25 +++++++++++++++++++
2 files changed, 28 insertions(+), 1 deletion(-)
diff --git a/frontend/src/flows/CreateCollectionDialog.tsx b/frontend/src/flows/CreateCollectionDialog.tsx
index 25fbfec41a..7417dab2f8 100644
--- a/frontend/src/flows/CreateCollectionDialog.tsx
+++ b/frontend/src/flows/CreateCollectionDialog.tsx
@@ -1,4 +1,5 @@
import { useState } from "react";
+import { flushSync } from "react-dom";
import { Button } from "@clickhouse/click-ui/Button";
import { Checkbox } from "@clickhouse/click-ui/Checkbox";
import { Select } from "@clickhouse/click-ui/Select";
@@ -25,7 +26,8 @@ export type ClaimCreateVersion = () => number;
* open when the answer lands waits for the new collection. The person is told whether it was
* made or one of that title already sits there; `typed` is shown when the answer names none. */
export function announceCreated(r: CollectionCreated, typed: string, org: string): void {
- invalidateSharedCollections({ name: r.namespace, org });
+ // Match the opening reload's priority so a delayed refresh cannot start a second read.
+ flushSync(() => invalidateSharedCollections({ name: r.namespace, org }));
const shown = r.title || typed || r.namespace;
toast(r.created ? `Created ${shown}` : `${shown} already exists here`, r.created ? "ok" : "info");
}
diff --git a/frontend/src/views/LibraryCollections.test.tsx b/frontend/src/views/LibraryCollections.test.tsx
index 6915d836ee..f8e13f7d07 100644
--- a/frontend/src/views/LibraryCollections.test.tsx
+++ b/frontend/src/views/LibraryCollections.test.tsx
@@ -1,5 +1,8 @@
// The place picker (a select, or the tree beside the page), the path and chips, the
// collection's menu, New collection, and how the list is read again after a write.
+import { startTransition } from "react";
+import { flushSync } from "react-dom";
+import { announceCreated } from "../flows/CreateCollectionDialog";
import { repeatedTitles } from "../lib/collections";
import { act, cleanup, fireEvent, render, screen, waitFor, within } from "../test/rtl";
import { entry, matchOnly, Picker, read, ROWS, settle } from "../test/libraryCollections";
@@ -231,6 +234,28 @@ describe("useReadableCollections", () => {
expect(api.listCollections.mock.calls[0][1].signal.aborted).toBe(false);
});
+ it("coalesces a lower-priority create announcement with its synchronous opening read", async () => {
+ let latest: ReadableCollections | null = null;
+ function Holder() {
+ latest = useReadableCollections("acme");
+ return null;
+ }
+ api.listCollections.mockResolvedValue({ collections: [entry("col-a")], next_cursor: null });
+ render();
+ await settle();
+ const made = { namespace: "col-new", parent: "", created: true, title: "New" };
+ api.listCollections.mockResolvedValue({ collections: [entry("col-a"), entry(made.namespace)], next_cursor: null });
+ const reads = api.listCollections.mock.calls.length;
+ await act(async () => {
+ // Opening uses flushSync: the announcement must not arrive later at a lower priority.
+ startTransition(() => announceCreated(made, "New", "acme"));
+ flushSync(() => latest?.reload(made.namespace));
+ await Promise.resolve();
+ });
+ await settle();
+ expect(api.listCollections.mock.calls.length - reads).toBe(1);
+ });
+
it("requests document counts with every collection page", async () => {
api.listCollections
.mockResolvedValueOnce({ collections: [entry("col-a")], next_cursor: "col-a" })
From 4330390af27b96be8062fa6e7d760076404431a7 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 20:21:14 +0000
Subject: [PATCH 08/11] Check the named caller's cap after collection policy
updates
Signed-off-by: zlareb1
---
tests/integration/test_knowledge_sharing.py | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/tests/integration/test_knowledge_sharing.py b/tests/integration/test_knowledge_sharing.py
index b91ffe4490..61e88bff35 100644
--- a/tests/integration/test_knowledge_sharing.py
+++ b/tests/integration/test_knowledge_sharing.py
@@ -1161,7 +1161,8 @@ def test_only_collection_admins_change_its_spend_policy_and_keep_other_settings(
key: value for key, value in expected.items() if key != "updated_at"
}
status = gw.ok("alice", "cost.budget_status", {"namespace": collection})
- assert status["cap_source"] == "namespace" and status["cap_usd"] == 0.25
+ assert status["user_id"] == "alice"
+ assert status["cap_source"] == "namespace_user" and status["cap_usd"] == 0.125
gw.ok("alice", "collection.budget_set", {"namespace": collection, **original})
restored = gw.ok("alice", "namespace.get", {"namespace": collection})
assert {key: value for key, value in restored.items() if key != "updated_at"} == {
From d43e285737e23e3c04f6ad2ea45a38cc41dfcfb9 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 21:23:06 +0000
Subject: [PATCH 09/11] Assert the end-user refusal on the directory route
Signed-off-by: zlareb1
---
tests/integration/test_knowledge_sharing.py | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/tests/integration/test_knowledge_sharing.py b/tests/integration/test_knowledge_sharing.py
index 61e88bff35..30e378bf67 100644
--- a/tests/integration/test_knowledge_sharing.py
+++ b/tests/integration/test_knowledge_sharing.py
@@ -1173,4 +1173,6 @@ def test_only_collection_admins_change_its_spend_policy_and_keep_other_settings(
"namespace.register",
{"namespace": collection, "owner_email": "user:alice", "daily_cost_cap_usd": 1},
)
- assert wrong_route.status_code == 422 and "collection operations only" in wrong_route.text
+ assert wrong_route.status_code == 403
+ assert "namespace.register is not open to an end user" in wrong_route.text
+ assert gw.ok("alice", "namespace.get", {"namespace": collection}) == restored
From 16fc75f3cdec9a6a24ded9260f38c6d116f3a506 Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 21:40:07 +0000
Subject: [PATCH 10/11] Replicated erasure fixtures provide isolated write
leases
Fenced memory inserts require a lease table in the selected schema. Give each fixture database its own Keeper root while preserving the replicated content checks.
Signed-off-by: zlareb1
(cherry picked from commit 96be03c3d5fa4062c8ca44226a5e138642c86504)
Signed-off-by: zlareb1
---
.../integration/test_erasure_replicated_ch.py | 5 +
tests/unit/test_erasure_replicated_fixture.py | 96 +++++++++++++++++++
2 files changed, 101 insertions(+)
create mode 100644 tests/unit/test_erasure_replicated_fixture.py
diff --git a/tests/integration/test_erasure_replicated_ch.py b/tests/integration/test_erasure_replicated_ch.py
index 4c687d0cce..680c4998e8 100644
--- a/tests/integration/test_erasure_replicated_ch.py
+++ b/tests/integration/test_erasure_replicated_ch.py
@@ -73,6 +73,11 @@ def db(raw: Any, monkeypatch: pytest.MonkeyPatch) -> Iterator[str]:
parameters={"db": name},
).result_rows
assert engines == [(True,)]
+ # Fenced memory inserts need leases isolated from the source schema's keys.
+ raw.command(
+ f"CREATE TABLE {name}._migration_lock AS {source}._migration_lock "
+ f"ENGINE = KeeperMap('/{name}/_migration_lock') PRIMARY KEY name"
+ )
monkeypatch.setattr(settings, "ch_database", name)
yield name
finally:
diff --git a/tests/unit/test_erasure_replicated_fixture.py b/tests/unit/test_erasure_replicated_fixture.py
new file mode 100644
index 0000000000..3147871591
--- /dev/null
+++ b/tests/unit/test_erasure_replicated_fixture.py
@@ -0,0 +1,96 @@
+"""The replicated erasure fixture supplies an isolated write-lease store."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from server.core import leases
+from server.settings import settings
+from tests.integration import test_erasure_replicated_ch as replicated
+from tests.unit.claims_fake import FakeLockTable
+
+
+class Schema:
+ def __init__(self):
+ self.tables = {}
+ self.commands = []
+
+ def command(self, sql):
+ self.commands.append(sql)
+ if sql.startswith("CREATE TABLE "):
+ self.tables[sql.split()[2]] = sql
+
+ def query(self, sql, parameters=None):
+ if "engine_full" in sql:
+ assert parameters["db"] == "source_schema"
+ return SimpleNamespace(result_rows=[("ReplacingMergeTree(version) ORDER BY tuple()",)])
+ assert "SELECT DISTINCT engine" in sql
+ flags = {"ENGINE = Replicated" in ddl for ddl in self.tables.values()}
+ return SimpleNamespace(result_rows=[(flag,) for flag in sorted(flags)])
+
+
+class FixtureLocks(FakeLockTable):
+ def __init__(self, schema):
+ super().__init__()
+ self.schema = schema
+
+ async def query_one(self, sql, params=None):
+ if "loom._migration_lock" in sql:
+ if f"{settings.ch_database}._migration_lock" not in self.schema.tables:
+ raise RuntimeError("Unknown table _migration_lock")
+ return await super().query_one(sql, params)
+
+
+@pytest.fixture
+def isolated_schema(monkeypatch):
+ monkeypatch.setattr(settings, "ch_database", "source_schema")
+ schema = Schema()
+ stream = replicated.db.__wrapped__(schema, monkeypatch)
+ name = next(stream)
+ try:
+ yield schema, name
+ finally:
+ stream.close()
+ assert schema.commands[-1] == f"DROP DATABASE IF EXISTS {name} SYNC"
+
+
+async def test_replicated_erasure_fixture_can_take_and_release_a_write_lease(isolated_schema):
+ schema, name = isolated_schema
+ keeper = FixtureLocks(schema)
+ lease = await leases.take("memory_insert/fixture", ttl_s=60, ch=keeper)
+ assert lease is not None and lease.held
+ assert settings.ch_database == name
+ await lease.release()
+ assert keeper.keys == {}
+
+
+async def test_a_missing_fixture_lease_table_still_refuses(isolated_schema):
+ schema, name = isolated_schema
+ schema.tables.pop(f"{name}._migration_lock", None)
+ with pytest.raises(leases.LeaseUnavailable):
+ await leases.take("memory_insert/fixture", ttl_s=60, ch=FixtureLocks(schema))
+
+
+def test_fixture_lease_paths_are_separate_from_source_and_each_other(monkeypatch):
+ paths = []
+ for _ in range(2):
+ with monkeypatch.context() as patch:
+ patch.setattr(settings, "ch_database", "source_schema")
+ schema = Schema()
+ stream = replicated.db.__wrapped__(schema, patch)
+ name = next(stream)
+ try:
+ ddl = schema.tables[f"{name}._migration_lock"]
+ assert "AS source_schema._migration_lock" in ddl
+ assert f"KeeperMap('/{name}/_migration_lock')" in ddl
+ assert "PRIMARY KEY name" in ddl
+ assert all(
+ "ENGINE = Replicated" in schema.tables[f"{name}.{table}"]
+ for table in replicated._TABLES
+ )
+ paths.append(name)
+ finally:
+ stream.close()
+ assert paths[0] != paths[1]
From 4ad5016f64da700df45397fe2b91034b837a893f Mon Sep 17 00:00:00 2001
From: zlareb1
Date: Fri, 20 Nov 2026 22:17:13 +0000
Subject: [PATCH 11/11] Control the coalescing clock in the close test
Keep all four submissions in the same logical window so the test exercises
close flushing pending writes before the transport closes. Preserve the
existing inputs, scheduling yields and result assertion.
Signed-off-by: zlareb1
(cherry picked from commit 5a15b566aa7628b3b855763a840cfb5503708c5c)
Signed-off-by: zlareb1
---
tests/unit/test_sdk_set_coalescer.py | 9 ++++++++-
1 file changed, 8 insertions(+), 1 deletion(-)
diff --git a/tests/unit/test_sdk_set_coalescer.py b/tests/unit/test_sdk_set_coalescer.py
index 25b6ce2c17..fe34f658bf 100644
--- a/tests/unit/test_sdk_set_coalescer.py
+++ b/tests/unit/test_sdk_set_coalescer.py
@@ -503,7 +503,14 @@ async def test_flush_sets_sends_the_gathered_batch_now(agent: Agent) -> None:
assert sum(1 for r in results if r.get("coalesced")) == 3
-async def test_close_flushes_before_the_pool_closes(agent: Agent) -> None:
+async def test_close_flushes_before_the_pool_closes(
+ agent: Agent, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from tests.unit.clock_fake import ManualClock
+
+ loop = asyncio.get_running_loop()
+ clock = ManualClock(t=loop.time())
+ monkeypatch.setattr(loop, "time", clock.monotonic)
t: Any = agent.transport
tasks = [asyncio.ensure_future(agent.memory.set(f"k{i}", i)) for i in range(4)]
await asyncio.sleep(0)