From 18eac3b58b5a9bd901b4a62394a680550cc7bac2 Mon Sep 17 00:00:00 2001 From: rahulsjha <132360698+rahulsjha@users.noreply.github.com> Date: Sun, 22 Nov 2026 02:23:29 +0530 Subject: [PATCH 1/4] Generate the Ruby SDK's op methods and error classes from the registry scripts/codegen/sdk_rb_gen.py writes sdk/ruby/lib/clickhouse/loom/generated/: ops.rb holds OPS (one OpSpec per served op: idempotency, read-only, role, maturity, field names) and one class per op group with one method per op, named as the Python SDK names them; errors.rb holds one Error subclass per server code, from the same sources as docs/reference/errors.md. --check runs in make lint, and tests/unit/test_sdk_rb_generated.py fails on drift. Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com> --- .claude/rules/wire-ops.md | 2 +- CONTRIBUTING.md | 2 +- Makefile | 1 + docs/development/adding-an-operation.md | 1 + docs/development/code-generation.md | 1 + scripts/codegen/sdk_rb_gen.py | 292 ++ .../lib/clickhouse/loom/generated/errors.rb | 1171 ++++++ sdk/ruby/lib/clickhouse/loom/generated/ops.rb | 3189 +++++++++++++++++ tests/unit/test_sdk_rb_generated.py | 62 + 9 files changed, 4719 insertions(+), 2 deletions(-) create mode 100644 scripts/codegen/sdk_rb_gen.py create mode 100644 sdk/ruby/lib/clickhouse/loom/generated/errors.rb create mode 100644 sdk/ruby/lib/clickhouse/loom/generated/ops.rb create mode 100644 tests/unit/test_sdk_rb_generated.py diff --git a/.claude/rules/wire-ops.md b/.claude/rules/wire-ops.md index 8bd818b89e..f48af99d1d 100644 --- a/.claude/rules/wire-ops.md +++ b/.claude/rules/wire-ops.md @@ -13,7 +13,7 @@ paths: - `server/operations/base.py` defines `Operation`, `Role` and `grant_rank`; `server/transport/mcp_primer.py` renders the primer and answers `prompts/*` / `resources/*`; `server/observability/budgets.py::effective_budget_ms` resolves each op's latency budget (runtime and per-consumer overrides). - Nothing below `server/transport/` imports it (`tests/unit/test_transport_layering.py`), and `package_contract_allowlist.txt` only shrinks: fix the import, never add an exception. - Models in `server//api/models_.py` import no handler; the `Operation` and its `OPERATIONS` entry live in `ops_.py`. `server/operations/registry.py` imports each list, and the handler in `server//app/` imports its models at module top. Transports discover ops from the registry; a change that edits transport code to add an op is in the wrong place. -- After any op or field change: `python -m scripts.codegen.` for `sdk_py_gen`, `sdk_py_client_gen`, `sdk_ts_gen`, `docs_reference`, `op_reach_census`. Generated SDK files are never edited by hand. +- After any op or field change: `python -m scripts.codegen.` for `sdk_py_gen`, `sdk_py_client_gen`, `sdk_ts_gen`, `sdk_rb_gen`, `docs_reference`, `op_reach_census`. Generated SDK files are never edited by hand. - Whether an agent calls `memory.set` or `memory.pin` is the model's judgement from the tool description (`server/transport/mcp_descriptions.py`), not a pattern match: change the wording, not a regex. - A field description is what a model reads when it calls the tool: one sentence on what the value does, its unit and its default. - The default MCP `tools/list` has a token ceiling (`test_mcp_listing_budget.py`); a new tool joins the default listing only when an agent needs it without asking. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 77a3c831f7..72007b8471 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -183,7 +183,7 @@ Adding a new operation ([full walkthrough](./docs/development/adding-an-operatio 1. Define `Input` / `Output` Pydantic models in `server//api/models_.py`. 2. Write the handler in `server//app/.py`; it imports the models at module top. 3. Declare the `Operation` in `server//api/ops_.py` and append it to that module's `OPERATIONS`. -4. Regenerate the SDK op tables and the Python per-op client: `python scripts/codegen/sdk_py_gen.py`, `python scripts/codegen/sdk_py_client_gen.py` and `python scripts/codegen/sdk_ts_gen.py` (CI runs each with `--check`). Add a method to the hand-written client in `sdk/python/loom/.py` when the op belongs in the high-level API. +4. Regenerate the SDK op tables and the Python per-op client: `python scripts/codegen/sdk_py_gen.py`, `python scripts/codegen/sdk_py_client_gen.py`, `python scripts/codegen/sdk_ts_gen.py` and `python scripts/codegen/sdk_rb_gen.py` (each has a `--check`). Add a method to the hand-written client in `sdk/python/loom/.py` when the op belongs in the high-level API. 5. Add unit tests, and an integration test under `tests/integration/` for a new read or write path. The HTTP and MCP transports discover registered operations; you don't touch transport code. diff --git a/Makefile b/Makefile index 760be5964c..95e67088b3 100644 --- a/Makefile +++ b/Makefile @@ -325,6 +325,7 @@ lint: $(PYTHON) scripts/codegen/sdk_py_client_gen.py --check $(PYTHON) scripts/codegen/sdk_py_admin_gen.py --check $(PYTHON) scripts/codegen/sdk_ts_gen.py --check + $(PYTHON) scripts/codegen/sdk_rb_gen.py --check $(PYTHON) scripts/codegen/agent_plugin_sync.py --check $(PYTHON) scripts/codegen/settings_reference.py --check $(PYTHON) scripts/codegen/settings_schema.py --check diff --git a/docs/development/adding-an-operation.md b/docs/development/adding-an-operation.md index 32e9eb1349..24582f484c 100644 --- a/docs/development/adding-an-operation.md +++ b/docs/development/adding-an-operation.md @@ -163,6 +163,7 @@ If the leakage suite cannot synthesize a body for your op, it reports it; add a python scripts/codegen/sdk_py_gen.py # sdk/python/loom/ops.py python scripts/codegen/sdk_py_client_gen.py # sdk/python/loom/client.py python scripts/codegen/sdk_ts_gen.py # sdk/typescript/src/generated/ops.ts +python scripts/codegen/sdk_rb_gen.py # sdk/ruby/lib/clickhouse/loom/generated/*.rb python scripts/codegen/op_reach_census.py --write-manifest # server/operations/reach_manifest.py python scripts/codegen/docs_reference.py # generated regions of docs/reference/*.md make format diff --git a/docs/development/code-generation.md b/docs/development/code-generation.md index 3f6e27200e..72f26e2845 100644 --- a/docs/development/code-generation.md +++ b/docs/development/code-generation.md @@ -26,6 +26,7 @@ ruff formatting, an atomic write, and the write-or-check protocol). | `sdk_py_client_gen.py` | `sdk/python/loom/client.py`: `OpsClient`, one method per op (`agent.client.tracker.source_add`), typed with the `ops.py` names | `server.operations.registry.ALL_OPERATIONS` | yes | | `sdk_py_admin_gen.py` | `sdk/python/loom/admin_routes.py`: `AdminRoutes`, one method per `/v1/admin/*` route (`agent.deployment.routes.settings_set`) | the `/v1/admin/*` routers: each route's method, path, gate and docstring | yes | | `sdk_ts_gen.py` | `sdk/typescript/src/generated/ops.ts`: one interface per model, the `OPS` table, the `OpMap` type | `server.operations.registry.ALL_OPERATIONS` (the models' JSON Schemas) | yes | +| `sdk_rb_gen.py` | `sdk/ruby/lib/clickhouse/loom/generated/`: `ops.rb` (the `OPS` table, one class per op group, one method per op) and `errors.rb` (one `Error` subclass per server code) | `server.operations.registry.ALL_OPERATIONS`; the error codes as `docs_reference.py` collects them | yes | | `agent_plugin_sync.py` | the Codex plugin's copies of the hook scripts (`hooks/*.mjs`), the shared library (`lib/*.mjs`), the skills and the listing icon (`assets/`), byte-identical with the executable bit | `integrations/claude-code-plugin/` | yes | | `settings_reference.py` | the generated [configuration reference](../reference/configuration.md) | `server/settings/catalog.py`: each field's env var, type, default, and the comment above it | yes | | `settings_schema.py` | `schemas/loom-settings.schema.json`, the JSON Schema of the YAML settings file | the settings fields' types, bounds, defaults and comments, secrets left out | yes | diff --git a/scripts/codegen/sdk_rb_gen.py b/scripts/codegen/sdk_rb_gen.py new file mode 100644 index 0000000000..709015271d --- /dev/null +++ b/scripts/codegen/sdk_rb_gen.py @@ -0,0 +1,292 @@ +"""Generate the Ruby SDK's operation table, its per-op methods and its error classes +from the server's registry (the twins are sdk_py_client_gen.py and sdk_ts_gen.py). + +Two files under `sdk/ruby/lib/clickhouse/loom/generated/`: + +- `ops.rb`: `OPS`, one `OpSpec` per served op (idempotency, read-only, role, + maturity, the input's field names and the required ones), and one class per op + group with one method per op. `client..(**fields)` posts + `/v1/.`: the group is the op name's first segment and the method is + the rest with `.` turned into `_`, as in the Python SDK (`tracker.source.add` → + `client.tracker.source_add`). A method that would shadow a method every Ruby + object has takes a trailing underscore (`memory.inspect` → `memory.inspect_`). +- `errors.rb`: one `Error` subclass per server error code (`PINNED_CONFLICT` → + `ClickHouse::Loom::PinnedConflict`), from the same sources as the errors + reference (`docs_reference.py`), and `ERROR_CLASSES`, the code → class map + `Error.from_response` reads. + +So a new server op or error code reaches the Ruby SDK by regeneration alone. + + python scripts/codegen/sdk_rb_gen.py # write the files + python scripts/codegen/sdk_rb_gen.py --check # exit 1 when a file is stale (CI) +""" + +from __future__ import annotations + +import argparse +import json +import sys +from collections import defaultdict +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: # run as a file + sys.path.insert(0, str(ROOT)) + +from scripts.codegen.common import GeneratedFile, OpFacts, pascal # noqa: E402 + +COMMAND = "python scripts/codegen/sdk_rb_gen.py" +OUT_DIR = ROOT / "sdk" / "ruby" / "lib" / "clickhouse" / "loom" / "generated" +HEADER = ( + "# frozen_string_literal: true\n" + "\n" + "# GENERATED by scripts/codegen/sdk_rb_gen.py from {source} — do not edit.\n" + f"# Regenerate: {COMMAND} (CI: --check)\n" +) + +#: The public methods of every Ruby object (`Object.public_instance_methods` on +#: Ruby 3.1 to 3.3). A generated method of one of these names would shadow it, so +#: irb or a test failure printing a group would make an HTTP call. +RUBY_OBJECT_METHODS = frozenset( + "__id__ __send__ class clone define_singleton_method display dup enum_for eql? equal? " + "extend freeze frozen? hash inspect instance_eval instance_exec instance_of? " + "instance_variable_defined? instance_variable_get instance_variable_set " + "instance_variables is_a? itself kind_of? method methods nil? object_id private_methods " + "protected_methods public_method public_methods public_send remove_instance_variable " + "respond_to? send singleton_class singleton_method singleton_methods tap then to_enum " + "to_s yield_self".split() +) + +#: Methods the client defines by hand. A group of one of these names would be +#: hidden behind it; `search` is the one the client resolves itself (`client.search` +#: with no query is the `search.*` group). +CLIENT_METHODS = frozenset( + {"base_url", "call", "delete", "get", "identity", "op_group", "retry_policy", "set"} +) + +#: Constants `ClickHouse::Loom` defines by hand, and the top-level ones its code names +#: unqualified (`Timeout::Error`, `JSON.parse`, ...): an error class of one of these +#: names would hide it inside the module, so it takes an `Error` suffix instead. +RESERVED_CONSTANTS = frozenset( + { + "CATEGORIES", + "Client", + "Configuration", + "DeleteResult", + "Error", + "Generated", + "Memory", + "OpGroup", + "OpSpec", + "RetryAfter", + "RetryPolicy", + "SearchHit", + "SearchResult", + "SetResult", + # top-level constants the hand-written code uses unqualified + "DidYouMean", + "Errno", + "Float", + "IOError", + "JSON", + "Net", + "OpenSSL", + "SecureRandom", + "SocketError", + "Struct", + "Time", + "Timeout", + "URI", + } +) + +#: The keyword a generated method takes its transport options under +#: (`idempotency_key:`, `retry_policy:`); no op may have a field of this name. +OPTIONS_KEYWORD = "request_options" + + +def split_op(name: str) -> tuple[str, str]: + """`tracker.source.add` → (`tracker`, `source_add`); `memory.inspect` → (`memory`, + `inspect_`).""" + group, _, rest = name.partition(".") + method = rest.replace(".", "_") + if method in RUBY_OBJECT_METHODS: + method += "_" + if not (group.isidentifier() and method.isidentifier() and group.islower()): + raise SystemExit(f"op {name!r} has no valid Ruby method name") + if group in RUBY_OBJECT_METHODS or group in CLIENT_METHODS: + raise SystemExit(f"op group {group!r} would shadow a method of the Ruby client") + return group, method + + +def _words(values: list[str]) -> str: + return "%w[" + " ".join(values) + "].freeze" if values else "[].freeze" + + +def _summary(schema: dict[str, object]) -> str: + text = str(schema.get("description") or "").strip().split("\n")[0] + return text if len(text) <= 160 else text[:157].rstrip() + "..." + + +def op_rows() -> list[tuple[OpFacts, list[str], list[str], str]]: + """(facts, field names, required field names, summary) per served op, by name.""" + from server.operations.registry import ALL_OPERATIONS + + rows = [] + for op in sorted(ALL_OPERATIONS, key=lambda o: o.name): + schema = op.input_model.model_json_schema() + fields = list(schema.get("properties") or {}) + if OPTIONS_KEYWORD in fields: + raise SystemExit(f"op {op.name!r} has a field named {OPTIONS_KEYWORD!r}") + bad = [f for f in fields if not f.isidentifier()] + if bad: + raise SystemExit( + f"op {op.name!r} has fields that are not Ruby keyword arguments: {bad}" + ) + required = [f for f in fields if f in set(schema.get("required") or [])] + rows.append((OpFacts.of(op), fields, required, _summary(schema))) + return rows + + +def build_ops() -> str: + rows = op_rows() + groups: dict[str, list[tuple[str, OpFacts, list[str], str]]] = defaultdict(list) + for facts, _fields, required, summary in rows: + group, method = split_op(facts.name) + if any(m == method for m, *_ in groups[group]): + raise SystemExit(f"two ops map to {group}.{method}") + groups[group].append((method, facts, required, summary)) + out = [ + HEADER.format(source="server.operations.registry.ALL_OPERATIONS"), + "module ClickHouse", + " module Loom", + " # Every served operation: its spec in OPS, and one method per op on the class", + " # of its group (`client.memory.set(...)` is `memory.set`).", + " module Generated", + f" OP_COUNT = {len(rows)}", + "", + " # The declared spec of every served op, by name; the HTTP path is /v1/.", + " OPS = {", + ] + for facts, fields, required, _summary in rows: + group, method = split_op(facts.name) + out.append( + f" {json.dumps(facts.name)} => OpSpec.new({json.dumps(facts.name)}, " + f"{json.dumps(group)}, {json.dumps(method)}, {str(facts.idempotent).lower()}, " + f"{str(facts.read_only).lower()}, {json.dumps(facts.role)}, " + f"{json.dumps(facts.maturity)}, {_words(fields)}, {_words(required)})," + ) + out += [" }.freeze", ""] + for group in sorted(groups): + out += _group_class(group, groups[group]) + out += [" # The class of each op group, by name.", " GROUPS = {"] + out += [f" {json.dumps(g)} => {pascal(g)}Ops," for g in sorted(groups)] + out += [ + " }.freeze", + "", + " # One accessor per op group on the client: `client.memory`, `client.task`, ...", + " module GroupAccessors", + ] + for i, group in enumerate(sorted(groups)): + out += ([""] if i else []) + [ + f" def {group}", + f" op_group({json.dumps(group)})", + " end", + ] + out += [" end", " end", " end", "end"] + return "\n".join(out) + "\n" + + +def _group_class(group: str, ops: list[tuple[str, OpFacts, list[str], str]]) -> list[str]: + out = [f" # The `{group}.*` operations.", f" class {pascal(group)}Ops < OpGroup"] + for i, (method, facts, required, summary) in enumerate(ops): + traits = [facts.role, "read-only" if facts.read_only else "writes"] + if facts.idempotent and not facts.read_only: + traits.append("Idempotency-Key") + if facts.maturity != "stable": + traits.append(facts.maturity) + out += [""] if i else [] + out.append(f" # `{facts.name}` ({', '.join(traits)}).") + if summary: + out.append(f" # {summary}") + if required: + out.append(f" # Required: {', '.join(required)}.") + out += [ + f" def {method}(body = nil, {OPTIONS_KEYWORD}: nil, **fields)", + f" call_op({json.dumps(facts.name)}, body, fields, {OPTIONS_KEYWORD})", + " end", + ] + return [*out, " end", ""] + + +def error_codes() -> list[tuple[str, str, int, str]]: + """(code, class name, HTTP status or 0, summary) for every code the errors + reference lists, by code.""" + from scripts.codegen.docs_reference import ( + CLASS_BY_CODE, + _code_literals, + _typed_errors, + ) + + typed = _typed_errors() + codes = sorted({*typed, *_code_literals(), *CLASS_BY_CODE}) + rows, taken = [], dict.fromkeys(RESERVED_CONSTANTS, "(hand-written)") + for code in codes: + name = pascal(code.lower()) + if name in RESERVED_CONSTANTS: + name += "Error" + if not name.isidentifier() or not name[:1].isupper(): + raise SystemExit(f"error code {code!r} has no valid Ruby class name") + if name in taken: + raise SystemExit(f"error codes {taken[name]!r} and {code!r} both map to {name}") + taken[name] = code + status, doc, _qual = typed.get(code, (0, "", "")) + rows.append((code, name, status, doc.strip().split("\n")[0])) + return rows + + +def build_errors() -> str: + rows = error_codes() + out = [ + HEADER.format(source="the server's error codes (as docs/reference/errors.md)"), + "module ClickHouse", + " module Loom", + ] + for code, name, status, doc in rows: + note = f"HTTP {status}. {doc}".strip() if status else "Server code" + out += [ + f" # `{code}`: {note}", + f" class {name} < Error", + f" CODE = {json.dumps(code)}", + " end", + "", + ] + out += [ + f" # The Error subclass for each server code ({len(rows)} codes); a code not", + " # listed raises Error itself.", + " ERROR_CLASSES = {", + *[f" {json.dumps(code)} => {name}," for code, name, _s, _d in rows], + " }.freeze", + " end", + "end", + ] + return "\n".join(out) + "\n" + + +TARGETS = ( + (GeneratedFile(OUT_DIR / "ops.rb", COMMAND), build_ops), + (GeneratedFile(OUT_DIR / "errors.rb", COMMAND), build_errors), +) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser( + description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter + ) + ap.add_argument("--check", action="store_true", help="exit 1 when a file is stale") + args = ap.parse_args(argv) + return max(target.sync(build(), check=args.check) for target, build in TARGETS) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/sdk/ruby/lib/clickhouse/loom/generated/errors.rb b/sdk/ruby/lib/clickhouse/loom/generated/errors.rb new file mode 100644 index 0000000000..4c9e15c08f --- /dev/null +++ b/sdk/ruby/lib/clickhouse/loom/generated/errors.rb @@ -0,0 +1,1171 @@ +# frozen_string_literal: true + +# GENERATED by scripts/codegen/sdk_rb_gen.py from the server's error codes (as docs/reference/errors.md) — do not edit. +# Regenerate: python scripts/codegen/sdk_rb_gen.py (CI: --check) + +module ClickHouse + module Loom + # `ACTIVITY_UNAVAILABLE`: Server code + class ActivityUnavailable < Error + CODE = "ACTIVITY_UNAVAILABLE" + end + + # `ADMISSION_CONTENDED`: HTTP 503. 503 — commits kept landing in this write's scope faster than it could re-check against them. + class AdmissionContended < Error + CODE = "ADMISSION_CONTENDED" + end + + # `AMBIGUOUS_KEY`: Server code + class AmbiguousKey < Error + CODE = "AMBIGUOUS_KEY" + end + + # `ANALYSIS_UNAVAILABLE`: HTTP 503. `insights.query` cannot run on this replica: the probe each process runs on an interval found, or a statement's login met, the analyst ClickHouse user missing, wider than the allowlist, or refusing… + class AnalysisUnavailable < Error + CODE = "ANALYSIS_UNAVAILABLE" + end + + # `ASSISTANT_SELF_CALL`: HTTP 403. An assistant answer's own token, or a token delegated from one, asked the assistant: the assistant never calls itself (docs/architecture/assistant.md). + class AssistantSelfCall < Error + CODE = "ASSISTANT_SELF_CALL" + end + + # `ASSISTANT_UNAVAILABLE`: HTTP 503. The assistant cannot answer in this web process: no LibreChat is configured (`LOOM_ASSISTANT_LIBRECHAT_URL`), auth is off (an answer is delegated from its caller's token), or this process's setup has… + class AssistantUnavailable < Error + CODE = "ASSISTANT_UNAVAILABLE" + end + + # `ASSISTANT_UPSTREAM_FAILED`: HTTP 503. LibreChat could not give this answer: it was unreachable, refused the request, ended the answer with an error, or ran past the answer's limit. + class AssistantUpstreamFailed < Error + CODE = "ASSISTANT_UPSTREAM_FAILED" + end + + # `AUTH_INSUFFICIENT`: HTTP 403. A public 403 that remains catchable as ``PermissionError`` internally. + class AuthInsufficient < Error + CODE = "AUTH_INSUFFICIENT" + end + + # `AUTH_INVALID`: Server code + class AuthInvalid < Error + CODE = "AUTH_INVALID" + end + + # `AUTH_UNAVAILABLE`: Server code + class AuthUnavailable < Error + CODE = "AUTH_UNAVAILABLE" + end + + # `BACKEND_TIMEOUT`: HTTP 504. 504 — a ClickHouse statement ran past its class deadline (reads 30 s, writes 60 s, DDL 300 s). + class BackendTimeout < Error + CODE = "BACKEND_TIMEOUT" + end + + # `BACKEND_UNAVAILABLE`: HTTP 503. 503 — ClickHouse, the document bucket, or a cell's tenancy read or placement failed; the router's lookup and operator API send the code when their directory fails. + class BackendUnavailable < Error + CODE = "BACKEND_UNAVAILABLE" + end + + # `BAD_BRANCH`: Server code + class BadBranch < Error + CODE = "BAD_BRANCH" + end + + # `BAD_BRIEF_KEY`: Server code + class BadBriefKey < Error + CODE = "BAD_BRIEF_KEY" + end + + # `BAD_CLASSIFICATION`: Server code + class BadClassification < Error + CODE = "BAD_CLASSIFICATION" + end + + # `BAD_CONFIG`: HTTP 422. 422 — a document source's config or items it cannot use, or a change it cannot make; the message, Loom's own, names what to fix. + class BadConfig < Error + CODE = "BAD_CONFIG" + end + + # `BAD_CONSTRAINT`: Server code + class BadConstraint < Error + CODE = "BAD_CONSTRAINT" + end + + # `BAD_CURSOR`: Server code + class BadCursor < Error + CODE = "BAD_CURSOR" + end + + # `BAD_ENUM_FIELD`: Server code + class BadEnumField < Error + CODE = "BAD_ENUM_FIELD" + end + + # `BAD_FIELD_NAME`: Server code + class BadFieldName < Error + CODE = "BAD_FIELD_NAME" + end + + # `BAD_FIELD_VALUE`: Server code + class BadFieldValue < Error + CODE = "BAD_FIELD_VALUE" + end + + # `BAD_INPUT`: Server code + class BadInput < Error + CODE = "BAD_INPUT" + end + + # `BAD_JOIN_POLICY`: Server code + class BadJoinPolicy < Error + CODE = "BAD_JOIN_POLICY" + end + + # `BAD_KIND`: Server code + class BadKind < Error + CODE = "BAD_KIND" + end + + # `BAD_LINK`: Server code + class BadLink < Error + CODE = "BAD_LINK" + end + + # `BAD_MAPPING`: Server code + class BadMapping < Error + CODE = "BAD_MAPPING" + end + + # `BAD_NAME`: Server code + class BadName < Error + CODE = "BAD_NAME" + end + + # `BAD_NAMESPACE`: Server code + class BadNamespace < Error + CODE = "BAD_NAMESPACE" + end + + # `BAD_ORG`: Server code + class BadOrg < Error + CODE = "BAD_ORG" + end + + # `BAD_PATTERN`: Server code + class BadPattern < Error + CODE = "BAD_PATTERN" + end + + # `BAD_REPO`: Server code + class BadRepo < Error + CODE = "BAD_REPO" + end + + # `BAD_REQUEST`: Server code + class BadRequest < Error + CODE = "BAD_REQUEST" + end + + # `BAD_SHA`: Server code + class BadSha < Error + CODE = "BAD_SHA" + end + + # `BAD_TIME`: Server code + class BadTime < Error + CODE = "BAD_TIME" + end + + # `BLACKLISTED`: Server code + class Blacklisted < Error + CODE = "BLACKLISTED" + end + + # `BLACKLIST_PATTERN_INVALID`: Server code + class BlacklistPatternInvalid < Error + CODE = "BLACKLIST_PATTERN_INVALID" + end + + # `BLOB_GONE`: Server code + class BlobGone < Error + CODE = "BLOB_GONE" + end + + # `BLOCK_PROMOTION_REFUSED`: Server code + class BlockPromotionRefused < Error + CODE = "BLOCK_PROMOTION_REFUSED" + end + + # `BRIEF_KEY_REQUIRED`: Server code + class BriefKeyRequired < Error + CODE = "BRIEF_KEY_REQUIRED" + end + + # `BRIEF_REVISION_MISMATCH`: Server code + class BriefRevisionMismatch < Error + CODE = "BRIEF_REVISION_MISMATCH" + end + + # `BRIEF_SELECTOR_REQUIRED`: Server code + class BriefSelectorRequired < Error + CODE = "BRIEF_SELECTOR_REQUIRED" + end + + # `CATEGORY_NOT_FOUND`: Server code + class CategoryNotFound < Error + CODE = "CATEGORY_NOT_FOUND" + end + + # `CHAR_LIMIT_EXCEEDED`: Server code + class CharLimitExceeded < Error + CODE = "CHAR_LIMIT_EXCEEDED" + end + + # `CODED_WIDTH_MISMATCH`: HTTP 503. 503 — a vector in the write is not the width its `Quantized` column was created at, so ClickHouse would refuse the insert. + class CodedWidthMismatch < Error + CODE = "CODED_WIDTH_MISMATCH" + end + + # `COLLECTION_NAME_TAKEN`: HTTP 409. 409 — no name could be had: the one asked for is used or was a deleted collection's (`deleted`), or every name a title derives is taken; `suggestion` is a free name when one was found, else ''. + class CollectionNameTaken < Error + CODE = "COLLECTION_NAME_TAKEN" + end + + # `CONFIG_DRIFT`: Server code + class ConfigDrift < Error + CODE = "CONFIG_DRIFT" + end + + # `CONFIRM_CANONICAL_KEY_MISMATCH`: Server code + class ConfirmCanonicalKeyMismatch < Error + CODE = "CONFIRM_CANONICAL_KEY_MISMATCH" + end + + # `CONFIRM_DUPLICATE_URI_MISMATCH`: Server code + class ConfirmDuplicateUriMismatch < Error + CODE = "CONFIRM_DUPLICATE_URI_MISMATCH" + end + + # `CONFIRM_REQUIRED`: Server code + class ConfirmRequired < Error + CODE = "CONFIRM_REQUIRED" + end + + # `CONFIRM_SUBJECT_MISMATCH`: Server code + class ConfirmSubjectMismatch < Error + CODE = "CONFIRM_SUBJECT_MISMATCH" + end + + # `CONFIRM_THREAD_ID_MISMATCH`: Server code + class ConfirmThreadIdMismatch < Error + CODE = "CONFIRM_THREAD_ID_MISMATCH" + end + + # `CONNECTION_UNAVAILABLE`: Server code + class ConnectionUnavailable < Error + CODE = "CONNECTION_UNAVAILABLE" + end + + # `CONSTRAINT_VIOLATION`: Server code + class ConstraintViolation < Error + CODE = "CONSTRAINT_VIOLATION" + end + + # `CONTRACT_FAILED`: Server code + class ContractFailed < Error + CODE = "CONTRACT_FAILED" + end + + # `CONTROL_UPGRADE_REQUIRED`: Server code + class ControlUpgradeRequired < Error + CODE = "CONTROL_UPGRADE_REQUIRED" + end + + # `CREDENTIAL_NOT_READONLY`: Server code + class CredentialNotReadonly < Error + CODE = "CREDENTIAL_NOT_READONLY" + end + + # `CREDENTIAL_READONLY_MODE`: Server code + class CredentialReadonlyMode < Error + CODE = "CREDENTIAL_READONLY_MODE" + end + + # `CREDENTIAL_REFUSED`: Server code + class CredentialRefused < Error + CODE = "CREDENTIAL_REFUSED" + end + + # `CROSS_SITE_REQUEST`: Server code + class CrossSiteRequest < Error + CODE = "CROSS_SITE_REQUEST" + end + + # `DEDUP_PAIR_NOT_FOUND`: Server code + class DedupPairNotFound < Error + CODE = "DEDUP_PAIR_NOT_FOUND" + end + + # `DEFAULT_NAMESPACE_REFUSED`: Server code + class DefaultNamespaceRefused < Error + CODE = "DEFAULT_NAMESPACE_REFUSED" + end + + # `DEFINITION_CEILING`: HTTP 409. 409 — the promotion would leave the namespace past `memory_shared_definitions_max` shared definitions: at the ceiling, demote one to add a new key; past it, demote until at most that many remain. + class DefinitionCeiling < Error + CODE = "DEFINITION_CEILING" + end + + # `DEFINITION_NAME_TAKEN`: HTTP 409. 409 — another shared definition holds this term or an alias; `conflicting_keys` names those definitions and `names` the folded names they hold. + class DefinitionNameTaken < Error + CODE = "DEFINITION_NAME_TAKEN" + end + + # `DEFINITION_PROMOTION_REFUSED`: HTTP 422. 422 — a definition is promoted only from its live namespace-wide row under a `definition/` key, to that same key, and a row of another type is never promoted under a `definition/` key. + class DefinitionPromotionRefused < Error + CODE = "DEFINITION_PROMOTION_REFUSED" + end + + # `DUPLICATE_FIELD`: Server code + class DuplicateField < Error + CODE = "DUPLICATE_FIELD" + end + + # `EMAIL_IN_USE`: Server code + class EmailInUse < Error + CODE = "EMAIL_IN_USE" + end + + # `EMBED_TIMEOUT`: HTTP 503. 503 — the query embedding did not answer within `memory_search_embed_bound_s` on any attempt. + class EmbedTimeout < Error + CODE = "EMBED_TIMEOUT" + end + + # `EMPTY_PREDICATE`: Server code + class EmptyPredicate < Error + CODE = "EMPTY_PREDICATE" + end + + # `ENTRY_LEASE_NOT_HELD`: HTTP 409. The pass that built this upload no longer holds its entry's lease: another pass may be indexing the entry, so its batch must not complete. + class EntryLeaseNotHeld < Error + CODE = "ENTRY_LEASE_NOT_HELD" + end + + # `ENUM_VIOLATION`: Server code + class EnumViolation < Error + CODE = "ENUM_VIOLATION" + end + + # `ERASURE_RUNNING`: HTTP 409. 409 — an erasure that will still run covers the namespace: a document source added or updated now would outlast it, since its first step may already have read the namespace's sources. + class ErasureRunning < Error + CODE = "ERASURE_RUNNING" + end + + # `EXPIRED`: Server code + class Expired < Error + CODE = "EXPIRED" + end + + # `EXTRACTION_FAILED`: Server code + class ExtractionFailed < Error + CODE = "EXTRACTION_FAILED" + end + + # `EXTRACTION_QUEUE_UNAVAILABLE`: Server code + class ExtractionQueueUnavailable < Error + CODE = "EXTRACTION_QUEUE_UNAVAILABLE" + end + + # `FORBIDDEN`: Server code + class Forbidden < Error + CODE = "FORBIDDEN" + end + + # `GATEWAY_REQUIRED`: HTTP 503. 503 — a model call named a host LOOM_INFERENCE_GATEWAY_HOSTS does not list while the gateway is required (`LOOM_INFERENCE_GATEWAY_REQUIRED`, or a workload token); the message names the host. + class GatewayRequired < Error + CODE = "GATEWAY_REQUIRED" + end + + # `GRANT_BUSY`: HTTP 503. 503 — another change to the same grant held it past the wait. + class GrantBusy < Error + CODE = "GRANT_BUSY" + end + + # `GRANT_WOULD_DOWNGRADE`: HTTP 409. 409 — `grants.create` asked for a role below the subject's current active grant on that namespace. + class GrantWouldDowngrade < Error + CODE = "GRANT_WOULD_DOWNGRADE" + end + + # `HANDLER_HTTP_ERROR`: Server code + class HandlerHttpError < Error + CODE = "HANDLER_HTTP_ERROR" + end + + # `HIGH_SENSITIVITY_PROMOTION_REFUSED`: Server code + class HighSensitivityPromotionRefused < Error + CODE = "HIGH_SENSITIVITY_PROMOTION_REFUSED" + end + + # `HOST_REFUSED`: Server code + class HostRefused < Error + CODE = "HOST_REFUSED" + end + + # `IDEMPOTENT_CONFLICT`: Server code + class IdempotentConflict < Error + CODE = "IDEMPOTENT_CONFLICT" + end + + # `IDEMPOTENT_IN_PROGRESS`: Server code + class IdempotentInProgress < Error + CODE = "IDEMPOTENT_IN_PROGRESS" + end + + # `IDEMPOTENT_TAKEN_OVER`: HTTP 503. 503 — this request's idempotency claim is no longer its own: a retry with the key took it over, or an erasure in the org fenced it. + class IdempotentTakenOver < Error + CODE = "IDEMPOTENT_TAKEN_OVER" + end + + # `IDENTITY_INCOMPLETE`: HTTP 400. A scoped token was presented without org+namespace in the request body. + class IdentityIncomplete < Error + CODE = "IDENTITY_INCOMPLETE" + end + + # `INTEGRATION_NOT_CONFIGURED`: Server code + class IntegrationNotConfigured < Error + CODE = "INTEGRATION_NOT_CONFIGURED" + end + + # `INTERNAL_ERROR`: HTTP 500. Base class. + class InternalError < Error + CODE = "INTERNAL_ERROR" + end + + # `INVALID_AGG`: Server code + class InvalidAgg < Error + CODE = "INVALID_AGG" + end + + # `INVALID_EMAIL`: Server code + class InvalidEmail < Error + CODE = "INVALID_EMAIL" + end + + # `INVALID_FORMAT`: Server code + class InvalidFormat < Error + CODE = "INVALID_FORMAT" + end + + # `INVALID_IDENTIFIER`: Server code + class InvalidIdentifier < Error + CODE = "INVALID_IDENTIFIER" + end + + # `INVALID_SCOPE`: Server code + class InvalidScope < Error + CODE = "INVALID_SCOPE" + end + + # `KEY_HOLDS_FACT`: Server code + class KeyHoldsFact < Error + CODE = "KEY_HOLDS_FACT" + end + + # `LOCKED`: Server code + class Locked < Error + CODE = "LOCKED" + end + + # `MAPPING_FAILED`: Server code + class MappingFailed < Error + CODE = "MAPPING_FAILED" + end + + # `MISDIRECTED_REQUEST`: Server code + class MisdirectedRequest < Error + CODE = "MISDIRECTED_REQUEST" + end + + # `MISSING_IDENTITY_FIELD`: Server code + class MissingIdentityField < Error + CODE = "MISSING_IDENTITY_FIELD" + end + + # `MISSING_REQUIRED_FIELD`: Server code + class MissingRequiredField < Error + CODE = "MISSING_REQUIRED_FIELD" + end + + # `MISSING_SCOPE`: Server code + class MissingScope < Error + CODE = "MISSING_SCOPE" + end + + # `MODEL_CALLS_DISABLED`: HTTP 403. The org's admin switched its model calls off: nothing is sent for it. + class ModelCallsDisabled < Error + CODE = "MODEL_CALLS_DISABLED" + end + + # `MODEL_CALL_DEFERRED`: HTTP 503. 503 — the inference gateway asked the call's identity to wait for `retry_after_s`, its `Retry-After`. + class ModelCallDeferred < Error + CODE = "MODEL_CALL_DEFERRED" + end + + # `MODEL_CALL_REFUSED`: HTTP 403. 403 — the inference gateway refused the call for the identity it was made for: that identity's refusal, not the provider's failure. + class ModelCallRefused < Error + CODE = "MODEL_CALL_REFUSED" + end + + # `MODEL_CALL_UNATTRIBUTED`: HTTP 500. A model call with no customer to bill: a caller that set none (a job that did not name the org of its rows). + class ModelCallUnattributed < Error + CODE = "MODEL_CALL_UNATTRIBUTED" + end + + # `MODEL_CHANGE_IN_PROGRESS`: Server code + class ModelChangeInProgress < Error + CODE = "MODEL_CHANGE_IN_PROGRESS" + end + + # `MODEL_VALIDATION_FAILED`: Server code + class ModelValidationFailed < Error + CODE = "MODEL_VALIDATION_FAILED" + end + + # `NAMESPACE_CLAIMED`: Server code + class NamespaceClaimed < Error + CODE = "NAMESPACE_CLAIMED" + end + + # `NAMESPACE_HAS_ADMIN`: Server code + class NamespaceHasAdmin < Error + CODE = "NAMESPACE_HAS_ADMIN" + end + + # `NAMESPACE_INACTIVE`: Server code + class NamespaceInactive < Error + CODE = "NAMESPACE_INACTIVE" + end + + # `NAMESPACE_NOT_ACCESSIBLE`: Server code + class NamespaceNotAccessible < Error + CODE = "NAMESPACE_NOT_ACCESSIBLE" + end + + # `NAMESPACE_NOT_FOUND`: Server code + class NamespaceNotFound < Error + CODE = "NAMESPACE_NOT_FOUND" + end + + # `NAMESPACE_TAKEN`: Server code + class NamespaceTaken < Error + CODE = "NAMESPACE_TAKEN" + end + + # `NOT_A_REPO`: Server code + class NotARepo < Error + CODE = "NOT_A_REPO" + end + + # `NOT_A_SOURCE`: Server code + class NotASource < Error + CODE = "NOT_A_SOURCE" + end + + # `NOT_A_TRACKER_NAMESPACE`: Server code + class NotATrackerNamespace < Error + CODE = "NOT_A_TRACKER_NAMESPACE" + end + + # `NOT_FOUND`: Server code + class NotFound < Error + CODE = "NOT_FOUND" + end + + # `NO_CELL`: Server code + class NoCell < Error + CODE = "NO_CELL" + end + + # `NO_FIELDS_PROVIDED`: Server code + class NoFieldsProvided < Error + CODE = "NO_FIELDS_PROVIDED" + end + + # `NO_OPERATOR_CREDENTIAL`: Server code + class NoOperatorCredential < Error + CODE = "NO_OPERATOR_CREDENTIAL" + end + + # `NO_ROOT_SECRET`: Server code + class NoRootSecret < Error + CODE = "NO_ROOT_SECRET" + end + + # `NO_SIGNING_KEY`: HTTP 503. Kid `default` is retired (or the root secret signs neither HS256 nor RS256) and no keyring key is active here: nothing can be signed until an operator acts, so it carries no Retry-After. + class NoSigningKey < Error + CODE = "NO_SIGNING_KEY" + end + + # `NO_SUCH_CELL`: Server code + class NoSuchCell < Error + CODE = "NO_SUCH_CELL" + end + + # `OP_NOT_ON_MCP`: Server code + class OpNotOnMcp < Error + CODE = "OP_NOT_ON_MCP" + end + + # `ORG_MISMATCH`: Server code + class OrgMismatch < Error + CODE = "ORG_MISMATCH" + end + + # `ORG_TOO_LONG`: Server code + class OrgTooLong < Error + CODE = "ORG_TOO_LONG" + end + + # `OVERLOADED`: HTTP 503. 503 — too busy, retry: the ClickHouse pool or its streams, ClickHouse's shared memory, the document bucket's transfers or streams, an override's lock, a namespace's document-source lease or… + class Overloaded < Error + CODE = "OVERLOADED" + end + + # `OVERRIDE_NOT_STORED`: HTTP 409. 409 — ClickHouse refused to store the override (a read-only user, for example), so no process changed; the server log has the reason. + class OverrideNotStored < Error + CODE = "OVERRIDE_NOT_STORED" + end + + # `PASSWORD_LOGIN_SSO`: Server code + class PasswordLoginSso < Error + CODE = "PASSWORD_LOGIN_SSO" + end + + # `PERSONAL_NAMESPACE`: Server code + class PersonalNamespace < Error + CODE = "PERSONAL_NAMESPACE" + end + + # `PINNED_CONFLICT`: Server code + class PinnedConflict < Error + CODE = "PINNED_CONFLICT" + end + + # `POLICY_FORBIDDEN`: HTTP 403. 403 with the decision attached: which rules denied, per-leaf values, and any evaluation errors — "denied by policy" and "denied because the check could not run" are distinguishable by `errors`. + class PolicyForbidden < Error + CODE = "POLICY_FORBIDDEN" + end + + # `POSTGRES_REFUSED`: HTTP 500. 500 — Postgres refused a statement with a data or constraint error. + class PostgresRefused < Error + CODE = "POSTGRES_REFUSED" + end + + # `POSTGRES_UNAVAILABLE`: HTTP 503. 503 — Postgres, the memory authority, could not answer. + class PostgresUnavailable < Error + CODE = "POSTGRES_UNAVAILABLE" + end + + # `PRECONDITION_FAILED`: HTTP 409. 409 — `if_match_sha256` mismatch, an `approved_sha256` that no longer matches the definition's text, or an erasure that landed while a `namespace.restore` ran. + class PreconditionFailed < Error + CODE = "PRECONDITION_FAILED" + end + + # `PROBE_BUSY`: Server code + class ProbeBusy < Error + CODE = "PROBE_BUSY" + end + + # `PROBE_UNREACHABLE`: Server code + class ProbeUnreachable < Error + CODE = "PROBE_UNREACHABLE" + end + + # `PROCESS_STOPPING`: Server code + class ProcessStopping < Error + CODE = "PROCESS_STOPPING" + end + + # `PROJECTION_BEHIND`: HTTP 503. 503 — earlier commits in this namespace are not yet in ClickHouse, so a read of ClickHouse that must see every write the namespace committed would miss them. + class ProjectionBehind < Error + CODE = "PROJECTION_BEHIND" + end + + # `PUBLICATION_PENDING`: HTTP 503. 503: the write is committed and the delivery worker publishes its rows; it is not to be made again. + class PublicationPending < Error + CODE = "PUBLICATION_PENDING" + end + + # `RATE_LIMITED`: HTTP 429. 429 — the caller is over one of its admission limits (the org's in-flight requests); `retry_after_s` is the hint the SDK's retry layer honours. + class RateLimited < Error + CODE = "RATE_LIMITED" + end + + # `READS_LLM_FREE`: HTTP 409. 409 — `memory.ask` or `code.ask` asked for a model's answer while `LOOM_READS_LLM_FREE` is on. + class ReadsLlmFree < Error + CODE = "READS_LLM_FREE" + end + + # `RECALL_REQUIRES_FILTER`: Server code + class RecallRequiresFilter < Error + CODE = "RECALL_REQUIRES_FILTER" + end + + # `REMOTE_REFUSED`: Server code + class RemoteRefused < Error + CODE = "REMOTE_REFUSED" + end + + # `REPO_EXISTS`: Server code + class RepoExists < Error + CODE = "REPO_EXISTS" + end + + # `REPO_FROM_CONFIG`: Server code + class RepoFromConfig < Error + CODE = "REPO_FROM_CONFIG" + end + + # `REPO_NOT_INDEXED`: Server code + class RepoNotIndexed < Error + CODE = "REPO_NOT_INDEXED" + end + + # `REPO_QUOTA`: Server code + class RepoQuota < Error + CODE = "REPO_QUOTA" + end + + # `REQUEST_INTERRUPTED`: Server code + class RequestInterrupted < Error + CODE = "REQUEST_INTERRUPTED" + end + + # `RESERVED_BLOB_KEY`: Server code + class ReservedBlobKey < Error + CODE = "RESERVED_BLOB_KEY" + end + + # `RESOURCE_NOT_FOUND`: HTTP 404. + class ResourceNotFound < Error + CODE = "RESOURCE_NOT_FOUND" + end + + # `RESTRICTED_NOT_OPEN`: Server code + class RestrictedNotOpen < Error + CODE = "RESTRICTED_NOT_OPEN" + end + + # `ROLE_CEILING`: Server code + class RoleCeiling < Error + CODE = "ROLE_CEILING" + end + + # `SANDBOX_UNAVAILABLE`: Server code + class SandboxUnavailable < Error + CODE = "SANDBOX_UNAVAILABLE" + end + + # `SCHEMA_ACTIVE`: Server code + class SchemaActive < Error + CODE = "SCHEMA_ACTIVE" + end + + # `SCHEMA_NOT_FOUND`: Server code + class SchemaNotFound < Error + CODE = "SCHEMA_NOT_FOUND" + end + + # `SCHEMA_PENDING`: HTTP 503. 503 — the statement names a table that a migration this build carries but the service has not applied would create. + class SchemaPending < Error + CODE = "SCHEMA_PENDING" + end + + # `SCHEMA_REQUIRES_KEY`: Server code + class SchemaRequiresKey < Error + CODE = "SCHEMA_REQUIRES_KEY" + end + + # `SECTION_NOT_FOUND`: Server code + class SectionNotFound < Error + CODE = "SECTION_NOT_FOUND" + end + + # `SECTION_NOT_STRING`: Server code + class SectionNotString < Error + CODE = "SECTION_NOT_STRING" + end + + # `SELF_SERVICE_OFF`: Server code + class SelfServiceOff < Error + CODE = "SELF_SERVICE_OFF" + end + + # `SELF_SIGNUP_DISABLED`: Server code + class SelfSignupDisabled < Error + CODE = "SELF_SIGNUP_DISABLED" + end + + # `SELF_SIGNUP_SSO`: Server code + class SelfSignupSso < Error + CODE = "SELF_SIGNUP_SSO" + end + + # `SENSITIVE_DEFINITION_REFUSED`: HTTP 422. 422 — a definition labelled `medium`, or whose value reads as `medium` or `high`, is not promoted: the shared layer serves it to every reader of the namespace. + class SensitiveDefinitionRefused < Error + CODE = "SENSITIVE_DEFINITION_REFUSED" + end + + # `SESSION_PROTECTION_REQUIRED`: HTTP 409. 409 — session-content operations need the client's protection promise. + class SessionProtectionRequired < Error + CODE = "SESSION_PROTECTION_REQUIRED" + end + + # `SHARED_CONFLICT`: Server code + class SharedConflict < Error + CODE = "SHARED_CONFLICT" + end + + # `SIGNUP_IN_PROGRESS`: Server code + class SignupInProgress < Error + CODE = "SIGNUP_IN_PROGRESS" + end + + # `SIGNUP_ORG_FIXED`: Server code + class SignupOrgFixed < Error + CODE = "SIGNUP_ORG_FIXED" + end + + # `SIGNUP_UNAVAILABLE`: Server code + class SignupUnavailable < Error + CODE = "SIGNUP_UNAVAILABLE" + end + + # `SOURCE_DELETE_PENDING`: Server code + class SourceDeletePending < Error + CODE = "SOURCE_DELETE_PENDING" + end + + # `SOURCE_DOCUMENTS_KEPT`: Server code + class SourceDocumentsKept < Error + CODE = "SOURCE_DOCUMENTS_KEPT" + end + + # `SOURCE_EXISTS`: Server code + class SourceExists < Error + CODE = "SOURCE_EXISTS" + end + + # `SOURCE_FROM_CONFIG`: Server code + class SourceFromConfig < Error + CODE = "SOURCE_FROM_CONFIG" + end + + # `SOURCE_NOT_FOUND`: Server code + class SourceNotFound < Error + CODE = "SOURCE_NOT_FOUND" + end + + # `SOURCE_NOT_SERVED`: Server code + class SourceNotServed < Error + CODE = "SOURCE_NOT_SERVED" + end + + # `SOURCE_QUOTA`: Server code + class SourceQuota < Error + CODE = "SOURCE_QUOTA" + end + + # `SOURCE_REPLACED`: HTTP 409. 409 — the document source was removed and added again as another source during the call (an update's or a rotate's probe, a sync request); act on the current one. + class SourceReplaced < Error + CODE = "SOURCE_REPLACED" + end + + # `SOURCE_TAGS_LOCKED`: Server code + class SourceTagsLocked < Error + CODE = "SOURCE_TAGS_LOCKED" + end + + # `SOURCE_UNREACHABLE`: Server code + class SourceUnreachable < Error + CODE = "SOURCE_UNREACHABLE" + end + + # `SUBSTRING_NOT_FOUND`: Server code + class SubstringNotFound < Error + CODE = "SUBSTRING_NOT_FOUND" + end + + # `TASK_NOT_BLOCKABLE`: Server code + class TaskNotBlockable < Error + CODE = "TASK_NOT_BLOCKABLE" + end + + # `TASK_NOT_DEFERRABLE`: Server code + class TaskNotDeferrable < Error + CODE = "TASK_NOT_DEFERRABLE" + end + + # `TEAM_RULE_NOT_YOURS`: Server code + class TeamRuleNotYours < Error + CODE = "TEAM_RULE_NOT_YOURS" + end + + # `TENANCY_REFUSED`: HTTP 503. 503 — this cell's Postgres refused a row for an org the cell holds no tenancy row for (its org triggers), or a tenancy row (its `loom.tenancy` guard; docs/architecture/cells.md): the session that… + class TenancyRefused < Error + CODE = "TENANCY_REFUSED" + end + + # `TIMELINE_REQUIRES_FILTER`: Server code + class TimelineRequiresFilter < Error + CODE = "TIMELINE_REQUIRES_FILTER" + end + + # `TOKEN_NAME_TAKEN`: Server code + class TokenNameTaken < Error + CODE = "TOKEN_NAME_TAKEN" + end + + # `UNKNOWN_ARGUMENT`: Server code + class UnknownArgument < Error + CODE = "UNKNOWN_ARGUMENT" + end + + # `UNKNOWN_FIELD`: Server code + class UnknownField < Error + CODE = "UNKNOWN_FIELD" + end + + # `VALIDATION`: Server code + class Validation < Error + CODE = "VALIDATION" + end + + # `VALIDATION_FAILED`: HTTP 422. + class ValidationFailed < Error + CODE = "VALIDATION_FAILED" + end + + # `VECTOR_INPUT_TOO_LARGE`: HTTP 422. 422 — an entity filter exceeds 64 raw names, or its canonical aliases or summary seeds exceed 256 distinct names. + class VectorInputTooLarge < Error + CODE = "VECTOR_INPUT_TOO_LARGE" + end + + # `VIEWS_NOT_READABLE`: Server code + class ViewsNotReadable < Error + CODE = "VIEWS_NOT_READABLE" + end + + # `WORKING_MEMORY_BLOCK_NOT_FOUND`: Server code + class WorkingMemoryBlockNotFound < Error + CODE = "WORKING_MEMORY_BLOCK_NOT_FOUND" + end + + # `WORKING_MEMORY_LIMIT_EXCEEDED`: Server code + class WorkingMemoryLimitExceeded < Error + CODE = "WORKING_MEMORY_LIMIT_EXCEEDED" + end + + # `WRONG_CELL`: HTTP 409. 409 — the org a verified call acts in is placed in another cell of this deployment, or in none and the caller may not place it (docs/architecture/cells.md). + class WrongCell < Error + CODE = "WRONG_CELL" + end + + # The Error subclass for each server code (193 codes); a code not + # listed raises Error itself. + ERROR_CLASSES = { + "ACTIVITY_UNAVAILABLE" => ActivityUnavailable, + "ADMISSION_CONTENDED" => AdmissionContended, + "AMBIGUOUS_KEY" => AmbiguousKey, + "ANALYSIS_UNAVAILABLE" => AnalysisUnavailable, + "ASSISTANT_SELF_CALL" => AssistantSelfCall, + "ASSISTANT_UNAVAILABLE" => AssistantUnavailable, + "ASSISTANT_UPSTREAM_FAILED" => AssistantUpstreamFailed, + "AUTH_INSUFFICIENT" => AuthInsufficient, + "AUTH_INVALID" => AuthInvalid, + "AUTH_UNAVAILABLE" => AuthUnavailable, + "BACKEND_TIMEOUT" => BackendTimeout, + "BACKEND_UNAVAILABLE" => BackendUnavailable, + "BAD_BRANCH" => BadBranch, + "BAD_BRIEF_KEY" => BadBriefKey, + "BAD_CLASSIFICATION" => BadClassification, + "BAD_CONFIG" => BadConfig, + "BAD_CONSTRAINT" => BadConstraint, + "BAD_CURSOR" => BadCursor, + "BAD_ENUM_FIELD" => BadEnumField, + "BAD_FIELD_NAME" => BadFieldName, + "BAD_FIELD_VALUE" => BadFieldValue, + "BAD_INPUT" => BadInput, + "BAD_JOIN_POLICY" => BadJoinPolicy, + "BAD_KIND" => BadKind, + "BAD_LINK" => BadLink, + "BAD_MAPPING" => BadMapping, + "BAD_NAME" => BadName, + "BAD_NAMESPACE" => BadNamespace, + "BAD_ORG" => BadOrg, + "BAD_PATTERN" => BadPattern, + "BAD_REPO" => BadRepo, + "BAD_REQUEST" => BadRequest, + "BAD_SHA" => BadSha, + "BAD_TIME" => BadTime, + "BLACKLISTED" => Blacklisted, + "BLACKLIST_PATTERN_INVALID" => BlacklistPatternInvalid, + "BLOB_GONE" => BlobGone, + "BLOCK_PROMOTION_REFUSED" => BlockPromotionRefused, + "BRIEF_KEY_REQUIRED" => BriefKeyRequired, + "BRIEF_REVISION_MISMATCH" => BriefRevisionMismatch, + "BRIEF_SELECTOR_REQUIRED" => BriefSelectorRequired, + "CATEGORY_NOT_FOUND" => CategoryNotFound, + "CHAR_LIMIT_EXCEEDED" => CharLimitExceeded, + "CODED_WIDTH_MISMATCH" => CodedWidthMismatch, + "COLLECTION_NAME_TAKEN" => CollectionNameTaken, + "CONFIG_DRIFT" => ConfigDrift, + "CONFIRM_CANONICAL_KEY_MISMATCH" => ConfirmCanonicalKeyMismatch, + "CONFIRM_DUPLICATE_URI_MISMATCH" => ConfirmDuplicateUriMismatch, + "CONFIRM_REQUIRED" => ConfirmRequired, + "CONFIRM_SUBJECT_MISMATCH" => ConfirmSubjectMismatch, + "CONFIRM_THREAD_ID_MISMATCH" => ConfirmThreadIdMismatch, + "CONNECTION_UNAVAILABLE" => ConnectionUnavailable, + "CONSTRAINT_VIOLATION" => ConstraintViolation, + "CONTRACT_FAILED" => ContractFailed, + "CONTROL_UPGRADE_REQUIRED" => ControlUpgradeRequired, + "CREDENTIAL_NOT_READONLY" => CredentialNotReadonly, + "CREDENTIAL_READONLY_MODE" => CredentialReadonlyMode, + "CREDENTIAL_REFUSED" => CredentialRefused, + "CROSS_SITE_REQUEST" => CrossSiteRequest, + "DEDUP_PAIR_NOT_FOUND" => DedupPairNotFound, + "DEFAULT_NAMESPACE_REFUSED" => DefaultNamespaceRefused, + "DEFINITION_CEILING" => DefinitionCeiling, + "DEFINITION_NAME_TAKEN" => DefinitionNameTaken, + "DEFINITION_PROMOTION_REFUSED" => DefinitionPromotionRefused, + "DUPLICATE_FIELD" => DuplicateField, + "EMAIL_IN_USE" => EmailInUse, + "EMBED_TIMEOUT" => EmbedTimeout, + "EMPTY_PREDICATE" => EmptyPredicate, + "ENTRY_LEASE_NOT_HELD" => EntryLeaseNotHeld, + "ENUM_VIOLATION" => EnumViolation, + "ERASURE_RUNNING" => ErasureRunning, + "EXPIRED" => Expired, + "EXTRACTION_FAILED" => ExtractionFailed, + "EXTRACTION_QUEUE_UNAVAILABLE" => ExtractionQueueUnavailable, + "FORBIDDEN" => Forbidden, + "GATEWAY_REQUIRED" => GatewayRequired, + "GRANT_BUSY" => GrantBusy, + "GRANT_WOULD_DOWNGRADE" => GrantWouldDowngrade, + "HANDLER_HTTP_ERROR" => HandlerHttpError, + "HIGH_SENSITIVITY_PROMOTION_REFUSED" => HighSensitivityPromotionRefused, + "HOST_REFUSED" => HostRefused, + "IDEMPOTENT_CONFLICT" => IdempotentConflict, + "IDEMPOTENT_IN_PROGRESS" => IdempotentInProgress, + "IDEMPOTENT_TAKEN_OVER" => IdempotentTakenOver, + "IDENTITY_INCOMPLETE" => IdentityIncomplete, + "INTEGRATION_NOT_CONFIGURED" => IntegrationNotConfigured, + "INTERNAL_ERROR" => InternalError, + "INVALID_AGG" => InvalidAgg, + "INVALID_EMAIL" => InvalidEmail, + "INVALID_FORMAT" => InvalidFormat, + "INVALID_IDENTIFIER" => InvalidIdentifier, + "INVALID_SCOPE" => InvalidScope, + "KEY_HOLDS_FACT" => KeyHoldsFact, + "LOCKED" => Locked, + "MAPPING_FAILED" => MappingFailed, + "MISDIRECTED_REQUEST" => MisdirectedRequest, + "MISSING_IDENTITY_FIELD" => MissingIdentityField, + "MISSING_REQUIRED_FIELD" => MissingRequiredField, + "MISSING_SCOPE" => MissingScope, + "MODEL_CALLS_DISABLED" => ModelCallsDisabled, + "MODEL_CALL_DEFERRED" => ModelCallDeferred, + "MODEL_CALL_REFUSED" => ModelCallRefused, + "MODEL_CALL_UNATTRIBUTED" => ModelCallUnattributed, + "MODEL_CHANGE_IN_PROGRESS" => ModelChangeInProgress, + "MODEL_VALIDATION_FAILED" => ModelValidationFailed, + "NAMESPACE_CLAIMED" => NamespaceClaimed, + "NAMESPACE_HAS_ADMIN" => NamespaceHasAdmin, + "NAMESPACE_INACTIVE" => NamespaceInactive, + "NAMESPACE_NOT_ACCESSIBLE" => NamespaceNotAccessible, + "NAMESPACE_NOT_FOUND" => NamespaceNotFound, + "NAMESPACE_TAKEN" => NamespaceTaken, + "NOT_A_REPO" => NotARepo, + "NOT_A_SOURCE" => NotASource, + "NOT_A_TRACKER_NAMESPACE" => NotATrackerNamespace, + "NOT_FOUND" => NotFound, + "NO_CELL" => NoCell, + "NO_FIELDS_PROVIDED" => NoFieldsProvided, + "NO_OPERATOR_CREDENTIAL" => NoOperatorCredential, + "NO_ROOT_SECRET" => NoRootSecret, + "NO_SIGNING_KEY" => NoSigningKey, + "NO_SUCH_CELL" => NoSuchCell, + "OP_NOT_ON_MCP" => OpNotOnMcp, + "ORG_MISMATCH" => OrgMismatch, + "ORG_TOO_LONG" => OrgTooLong, + "OVERLOADED" => Overloaded, + "OVERRIDE_NOT_STORED" => OverrideNotStored, + "PASSWORD_LOGIN_SSO" => PasswordLoginSso, + "PERSONAL_NAMESPACE" => PersonalNamespace, + "PINNED_CONFLICT" => PinnedConflict, + "POLICY_FORBIDDEN" => PolicyForbidden, + "POSTGRES_REFUSED" => PostgresRefused, + "POSTGRES_UNAVAILABLE" => PostgresUnavailable, + "PRECONDITION_FAILED" => PreconditionFailed, + "PROBE_BUSY" => ProbeBusy, + "PROBE_UNREACHABLE" => ProbeUnreachable, + "PROCESS_STOPPING" => ProcessStopping, + "PROJECTION_BEHIND" => ProjectionBehind, + "PUBLICATION_PENDING" => PublicationPending, + "RATE_LIMITED" => RateLimited, + "READS_LLM_FREE" => ReadsLlmFree, + "RECALL_REQUIRES_FILTER" => RecallRequiresFilter, + "REMOTE_REFUSED" => RemoteRefused, + "REPO_EXISTS" => RepoExists, + "REPO_FROM_CONFIG" => RepoFromConfig, + "REPO_NOT_INDEXED" => RepoNotIndexed, + "REPO_QUOTA" => RepoQuota, + "REQUEST_INTERRUPTED" => RequestInterrupted, + "RESERVED_BLOB_KEY" => ReservedBlobKey, + "RESOURCE_NOT_FOUND" => ResourceNotFound, + "RESTRICTED_NOT_OPEN" => RestrictedNotOpen, + "ROLE_CEILING" => RoleCeiling, + "SANDBOX_UNAVAILABLE" => SandboxUnavailable, + "SCHEMA_ACTIVE" => SchemaActive, + "SCHEMA_NOT_FOUND" => SchemaNotFound, + "SCHEMA_PENDING" => SchemaPending, + "SCHEMA_REQUIRES_KEY" => SchemaRequiresKey, + "SECTION_NOT_FOUND" => SectionNotFound, + "SECTION_NOT_STRING" => SectionNotString, + "SELF_SERVICE_OFF" => SelfServiceOff, + "SELF_SIGNUP_DISABLED" => SelfSignupDisabled, + "SELF_SIGNUP_SSO" => SelfSignupSso, + "SENSITIVE_DEFINITION_REFUSED" => SensitiveDefinitionRefused, + "SESSION_PROTECTION_REQUIRED" => SessionProtectionRequired, + "SHARED_CONFLICT" => SharedConflict, + "SIGNUP_IN_PROGRESS" => SignupInProgress, + "SIGNUP_ORG_FIXED" => SignupOrgFixed, + "SIGNUP_UNAVAILABLE" => SignupUnavailable, + "SOURCE_DELETE_PENDING" => SourceDeletePending, + "SOURCE_DOCUMENTS_KEPT" => SourceDocumentsKept, + "SOURCE_EXISTS" => SourceExists, + "SOURCE_FROM_CONFIG" => SourceFromConfig, + "SOURCE_NOT_FOUND" => SourceNotFound, + "SOURCE_NOT_SERVED" => SourceNotServed, + "SOURCE_QUOTA" => SourceQuota, + "SOURCE_REPLACED" => SourceReplaced, + "SOURCE_TAGS_LOCKED" => SourceTagsLocked, + "SOURCE_UNREACHABLE" => SourceUnreachable, + "SUBSTRING_NOT_FOUND" => SubstringNotFound, + "TASK_NOT_BLOCKABLE" => TaskNotBlockable, + "TASK_NOT_DEFERRABLE" => TaskNotDeferrable, + "TEAM_RULE_NOT_YOURS" => TeamRuleNotYours, + "TENANCY_REFUSED" => TenancyRefused, + "TIMELINE_REQUIRES_FILTER" => TimelineRequiresFilter, + "TOKEN_NAME_TAKEN" => TokenNameTaken, + "UNKNOWN_ARGUMENT" => UnknownArgument, + "UNKNOWN_FIELD" => UnknownField, + "VALIDATION" => Validation, + "VALIDATION_FAILED" => ValidationFailed, + "VECTOR_INPUT_TOO_LARGE" => VectorInputTooLarge, + "VIEWS_NOT_READABLE" => ViewsNotReadable, + "WORKING_MEMORY_BLOCK_NOT_FOUND" => WorkingMemoryBlockNotFound, + "WORKING_MEMORY_LIMIT_EXCEEDED" => WorkingMemoryLimitExceeded, + "WRONG_CELL" => WrongCell, + }.freeze + end +end diff --git a/sdk/ruby/lib/clickhouse/loom/generated/ops.rb b/sdk/ruby/lib/clickhouse/loom/generated/ops.rb new file mode 100644 index 0000000000..5e5590de44 --- /dev/null +++ b/sdk/ruby/lib/clickhouse/loom/generated/ops.rb @@ -0,0 +1,3189 @@ +# frozen_string_literal: true + +# GENERATED by scripts/codegen/sdk_rb_gen.py from server.operations.registry.ALL_OPERATIONS — do not edit. +# Regenerate: python scripts/codegen/sdk_rb_gen.py (CI: --check) + +module ClickHouse + module Loom + # Every served operation: its spec in OPS, and one method per op on the class + # of its group (`client.memory.set(...)` is `memory.set`). + module Generated + OP_COUNT = 376 + + # The declared spec of every served op, by name; the HTTP path is /v1/. + OPS = { + "admin.users" => OpSpec.new("admin.users", "admin", "users", true, false, "org_admin", "experimental", %w[org namespace include_service_accounts limit].freeze, %w[org].freeze), + "agents.connected" => OpSpec.new("agents.connected", "agents", "connected", true, true, "viewer", "stable", %w[org namespace window_hours count_only].freeze, %w[org].freeze), + "assistant.ask" => OpSpec.new("assistant.ask", "assistant", "ask", false, false, "viewer", "experimental", %w[org namespace question history].freeze, %w[org namespace question].freeze), + "audit.list" => OpSpec.new("audit.list", "audit", "list", true, true, "viewer", "experimental", %w[org namespace event_type since limit cursor fields].freeze, %w[org].freeze), + "blacklist.add" => OpSpec.new("blacklist.add", "blacklist", "add", true, false, "writer", "experimental", %w[org namespace pattern pattern_type scope reason created_by sweep].freeze, %w[org namespace pattern].freeze), + "blacklist.list" => OpSpec.new("blacklist.list", "blacklist", "list", true, true, "viewer", "stable", %w[org namespace scope limit].freeze, %w[org namespace].freeze), + "blacklist.remove" => OpSpec.new("blacklist.remove", "blacklist", "remove", true, false, "admin", "experimental", %w[org pattern_id removed_by reason].freeze, %w[org pattern_id].freeze), + "blacklist.sweep" => OpSpec.new("blacklist.sweep", "blacklist", "sweep", true, false, "writer", "experimental", %w[org namespace pattern_id].freeze, %w[org namespace pattern_id].freeze), + "calibration.get" => OpSpec.new("calibration.get", "calibration", "get", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "code.ask" => OpSpec.new("code.ask", "code", "ask", true, true, "viewer", "stable", %w[org namespace agent user_id consumer question synthesize rerank no_cache token_budget].freeze, %w[question].freeze), + "code.backport_gap" => OpSpec.new("code.backport_gap", "code", "backport_gap", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer pr_number issue_number branches max_symbols exact history].freeze, [].freeze), + "code.backport_gaps" => OpSpec.new("code.backport_gaps", "code", "backport_gaps", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer branch wanted_only days limit].freeze, [].freeze), + "code.bisect_candidates" => OpSpec.new("code.bisect_candidates", "code", "bisect_candidates", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer symbols paths patterns issue_number text rerank deadline_ms fix_pr bad_version before after bad_sha good_version widen_to_directories wideners rescan limit marks].freeze, [].freeze), + "code.blame_range" => OpSpec.new("code.blame_range", "code", "blame_range", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer path start_line end_line from_version to_version from_sha to_sha limit reviews_per_pr stage mentions].freeze, %w[path start_line end_line].freeze), + "code.calibrate" => OpSpec.new("code.calibrate", "code", "calibrate", false, false, "admin", "stable", %w[org namespace agent user_id consumer].freeze, [].freeze), + "code.callees" => OpSpec.new("code.callees", "code", "callees", true, true, "viewer", "experimental", %w[include_lessons lesson_namespaces pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer name symbol_id depth max_nodes min_confidence include_ambiguous candidate_min_confidence pr_number edge_kinds].freeze, [].freeze), + "code.callers" => OpSpec.new("code.callers", "code", "callers", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer name symbol_id depth max_nodes min_confidence include_ambiguous candidate_min_confidence pr_number edge_kinds].freeze, [].freeze), + "code.context_pack" => OpSpec.new("code.context_pack", "code", "context_pack", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces org namespace agent user_id consumer pr_number task token_budget sections].freeze, [].freeze), + "code.context_packs" => OpSpec.new("code.context_packs", "code", "context_packs", true, true, "viewer", "stable", %w[org namespace agent user_id consumer limit offset pr_number].freeze, [].freeze), + "code.conventions" => OpSpec.new("code.conventions", "code", "conventions", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer pr_number head_sha files diff rules].freeze, [].freeze), + "code.coverage" => OpSpec.new("code.coverage", "code", "coverage", true, true, "viewer", "stable", %w[org namespace agent user_id consumer].freeze, [].freeze), + "code.coverage.unwatch" => OpSpec.new("code.coverage.unwatch", "code", "coverage_unwatch", true, false, "viewer", "stable", %w[org namespace agent user_id consumer commit inbox].freeze, %w[commit inbox].freeze), + "code.coverage.watch" => OpSpec.new("code.coverage.watch", "code", "coverage_watch", true, false, "viewer", "stable", %w[org namespace agent user_id consumer commit inbox].freeze, %w[commit inbox].freeze), + "code.coverage_claim" => OpSpec.new("code.coverage_claim", "code", "coverage_claim", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer symbol path setting limit].freeze, [].freeze), + "code.enclosing" => OpSpec.new("code.enclosing", "code", "enclosing", true, true, "viewer", "stable", %w[org namespace agent user_id consumer locations include_body token_budget neighbours neighbour_k].freeze, %w[locations].freeze), + "code.examples" => OpSpec.new("code.examples", "code", "examples", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer name symbol_id top_k].freeze, [].freeze), + "code.files" => OpSpec.new("code.files", "code", "files", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer glob stem path_prefix limit].freeze, [].freeze), + "code.first_build" => OpSpec.new("code.first_build", "code", "first_build", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer sha pr_number].freeze, [].freeze), + "code.grep" => OpSpec.new("code.grep", "code", "grep", true, true, "viewer", "stable", %w[org namespace agent user_id consumer pattern regex case_sensitive path_prefix cursor exclude_unit_ids mode limit path_globs exclude_globs langs namespaces neighbours neighbour_k deadline_ms].freeze, %w[pattern].freeze), + "code.history" => OpSpec.new("code.history", "code", "history", true, true, "viewer", "stable", %w[org namespace agent user_id consumer name symbol_id path numbers limit reviews_per_pr].freeze, [].freeze), + "code.impact" => OpSpec.new("code.impact", "code", "impact", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer name symbol_id depth files diff exclude_authors summary_only per_hop_limit offset pr_number].freeze, [].freeze), + "code.index_errors" => OpSpec.new("code.index_errors", "code", "index_errors", true, true, "viewer", "stable", %w[org namespace agent user_id consumer limit].freeze, [].freeze), + "code.index_status" => OpSpec.new("code.index_status", "code", "index_status", true, true, "viewer", "stable", %w[org namespace agent user_id consumer commit paths brief].freeze, [].freeze), + "code.map" => OpSpec.new("code.map", "code", "map", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer token_budget module_prefix].freeze, [].freeze), + "code.outcome" => OpSpec.new("code.outcome", "code", "outcome", true, false, "viewer", "stable", %w[org namespace agent user_id consumer trace_run_id action targets source tokens_saved spans reason].freeze, %w[action].freeze), + "code.outline" => OpSpec.new("code.outline", "code", "outline", true, true, "viewer", "experimental", %w[include_lessons lesson_namespaces org namespace agent user_id consumer path kinds token_budget].freeze, %w[path].freeze), + "code.path_guards" => OpSpec.new("code.path_guards", "code", "path_guards", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer from_symbol to_symbol mentions depth].freeze, %w[from_symbol to_symbol].freeze), + "code.pr_check" => OpSpec.new("code.pr_check", "code", "pr_check", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer title body paths symbols issues pr_number top_k].freeze, [].freeze), + "code.recent_commits" => OpSpec.new("code.recent_commits", "code", "recent_commits", true, true, "viewer", "stable", %w[org namespace agent user_id consumer limit].freeze, [].freeze), + "code.refresh" => OpSpec.new("code.refresh", "code", "refresh", false, false, "writer", "stable", %w[org namespace agent user_id consumer expected_head wait wait_timeout_seconds].freeze, [].freeze), + "code.reindex" => OpSpec.new("code.reindex", "code", "reindex", false, false, "admin", "experimental", %w[org namespace agent user_id consumer git_head].freeze, %w[git_head].freeze), + "code.repo.add" => OpSpec.new("code.repo.add", "code", "repo_add", false, false, "viewer", "stable", %w[org repo branch join_policy classification access_token git_proxy_identity path_prefixes exclude exclude_generated scip_producer branches].freeze, %w[org repo].freeze), + "code.repo.add_branch" => OpSpec.new("code.repo.add_branch", "code", "repo_add_branch", false, false, "admin", "stable", %w[org namespace branch].freeze, %w[org namespace branch].freeze), + "code.repo.remote_branches" => OpSpec.new("code.repo.remote_branches", "code", "repo_remote_branches", true, true, "viewer", "stable", %w[org repo access_token git_proxy_identity query limit].freeze, %w[org repo].freeze), + "code.repo.remove" => OpSpec.new("code.repo.remove", "code", "repo_remove", true, false, "admin", "stable", %w[org namespace confirm].freeze, %w[org namespace].freeze), + "code.repo.set_access" => OpSpec.new("code.repo.set_access", "code", "repo_set_access", true, false, "admin", "experimental", %w[org namespace classification join_policy confirm].freeze, %w[org namespace classification join_policy].freeze), + "code.repo.set_source" => OpSpec.new("code.repo.set_source", "code", "repo_set_source", true, false, "admin", "experimental", %w[org namespace tracker_namespaces].freeze, %w[org namespace tracker_namespaces].freeze), + "code.repos" => OpSpec.new("code.repos", "code", "repos", true, true, "viewer", "stable", %w[org namespace agent user_id consumer repo repos fields].freeze, [].freeze), + "code.review_brief" => OpSpec.new("code.review_brief", "code", "review_brief", true, true, "viewer", "experimental", %w[pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer pr_number merge_sha sections tier token_budget store open].freeze, [].freeze), + "code.scip_ingest" => OpSpec.new("code.scip_ingest", "code", "scip_ingest", true, false, "writer", "stable", %w[org namespace agent user_id consumer batch_id seq total_parts commit_sha base_sha producer payload entry_lease_holder].freeze, %w[batch_id seq total_parts payload].freeze), + "code.scip_status" => OpSpec.new("code.scip_status", "code", "scip_status", true, true, "viewer", "stable", %w[org namespace agent user_id consumer batch_id].freeze, %w[batch_id].freeze), + "code.search" => OpSpec.new("code.search", "code", "search", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces org namespace agent user_id consumer query top_k token_budget path_prefix cursor exclude_unit_ids rerank expand annotate bodies kind_prior pr_leg_before embedding_model fresh min_fan_in sort_by pattern regex case_sensitive path_globs exclude_globs langs legs track_path vector_model vector_shortlist llm_legs deadline_ms namespaces].freeze, %w[query].freeze), + "code.setting_facts" => OpSpec.new("code.setting_facts", "code", "setting_facts", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer name history_limit].freeze, %w[name].freeze), + "code.symbol" => OpSpec.new("code.symbol", "code", "symbol", true, true, "viewer", "stable", %w[org namespace agent user_id consumer name symbol_id include_body include_history include_examples include_lessons lesson_namespaces token_budget min_fan_in sort_by uses uses_limit uses_brief near_paths pr_number namespaces presence neighbours neighbour_k].freeze, [].freeze), + "code.symbol_history" => OpSpec.new("code.symbol_history", "code", "symbol_history", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer name symbol_id limit].freeze, [].freeze), + "code.test_gate" => OpSpec.new("code.test_gate", "code", "test_gate", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer files diff depth limit].freeze, [].freeze), + "code.test_home" => OpSpec.new("code.test_home", "code", "test_home", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer file_stems settings engine symbols limit].freeze, [].freeze), + "code.tests_for" => OpSpec.new("code.tests_for", "code", "tests_for", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer facets limit closest].freeze, %w[facets].freeze), + "code.trace" => OpSpec.new("code.trace", "code", "trace", true, true, "viewer", "stable", %w[org namespace agent user_id consumer trace max_frames token_budget].freeze, %w[trace].freeze), + "code.verify" => OpSpec.new("code.verify", "code", "verify", true, true, "viewer", "stable", %w[org namespace agent user_id consumer kind subject object depth].freeze, %w[kind subject].freeze), + "code.verify_citations" => OpSpec.new("code.verify_citations", "code", "verify_citations", true, true, "viewer", "experimental", %w[pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer text at_commit pr_number base_namespace limit].freeze, %w[text].freeze), + "collection.create" => OpSpec.new("collection.create", "collection", "create", true, false, "viewer", "experimental", %w[org namespace title derive_name parent description].freeze, %w[org].freeze), + "collection.delete" => OpSpec.new("collection.delete", "collection", "delete", true, false, "admin", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "collection.list" => OpSpec.new("collection.list", "collection", "list", true, true, "viewer", "experimental", %w[org limit include_document_counts cursor].freeze, %w[org].freeze), + "collection.move" => OpSpec.new("collection.move", "collection", "move", true, false, "admin", "experimental", %w[org namespace parent].freeze, %w[org namespace].freeze), + "conflicts.allowlist_list" => OpSpec.new("conflicts.allowlist_list", "conflicts", "allowlist_list", true, true, "viewer", "experimental", %w[org namespace limit].freeze, %w[org namespace].freeze), + "conflicts.allowlist_remove" => OpSpec.new("conflicts.allowlist_remove", "conflicts", "allowlist_remove", true, false, "admin", "experimental", %w[org namespace memory_key_a memory_key_b removed_by reason].freeze, %w[org namespace memory_key_a memory_key_b].freeze), + "conflicts.list" => OpSpec.new("conflicts.list", "conflicts", "list", true, true, "viewer", "stable", %w[org namespace limit before_version count_only fresh keys_only fields].freeze, %w[org namespace].freeze), + "conflicts.propose_revision" => OpSpec.new("conflicts.propose_revision", "conflicts", "propose_revision", true, true, "viewer", "experimental", %w[org namespace memory_id peer_id].freeze, %w[org namespace memory_id].freeze), + "conflicts.resolve" => OpSpec.new("conflicts.resolve", "conflicts", "resolve", true, false, "admin", "stable", %w[org namespace memory_id decision peer_id reason resolved_by].freeze, %w[org namespace memory_id decision].freeze), + "connection.disconnect" => OpSpec.new("connection.disconnect", "connection", "disconnect", true, false, "viewer", "experimental", %w[org kind].freeze, %w[org kind].freeze), + "connection.list" => OpSpec.new("connection.list", "connection", "list", true, true, "viewer", "experimental", %w[org].freeze, %w[org].freeze), + "consolidations.list" => OpSpec.new("consolidations.list", "consolidations", "list", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id limit].freeze, %w[org namespace].freeze), + "context.fetch" => OpSpec.new("context.fetch", "context", "fetch", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id blob_key offset limit pattern context_lines].freeze, %w[org namespace agent blob_key].freeze), + "context.offload" => OpSpec.new("context.offload", "context", "offload", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id content blob_key content_type summary ttl_seconds].freeze, %w[org namespace agent content].freeze), + "context.pack" => OpSpec.new("context.pack", "context", "pack", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id query situation procedure_explore_rate token_budget top_k read_scope mode include_knowledge include_conversations include_runs runs_limit include_chunks section_token_budgets block_order session_block only_sections include_decisions].freeze, %w[org namespace agent].freeze), + "conversation.append" => OpSpec.new("conversation.append", "conversation", "append", true, false, "writer", "stable", %w[org namespace agent thread_id msg_id role content reasoning user_id run_id metadata tokens].freeze, %w[org namespace agent thread_id role content].freeze), + "conversation.compact" => OpSpec.new("conversation.compact", "conversation", "compact", true, false, "writer", "experimental", %w[org namespace agent thread_id keep_recent min_to_compact].freeze, %w[org namespace agent thread_id].freeze), + "conversation.create" => OpSpec.new("conversation.create", "conversation", "create", true, false, "writer", "experimental", %w[org namespace agent thread_id title metadata run_id user_id].freeze, %w[org namespace agent thread_id].freeze), + "conversation.delete" => OpSpec.new("conversation.delete", "conversation", "delete", true, false, "admin", "experimental", %w[org namespace agent thread_id confirm_thread_id].freeze, %w[org namespace agent thread_id confirm_thread_id].freeze), + "conversation.get" => OpSpec.new("conversation.get", "conversation", "get", true, true, "viewer", "experimental", %w[org namespace agent thread_id include_messages limit offset order].freeze, %w[org namespace agent thread_id].freeze), + "conversation.list" => OpSpec.new("conversation.list", "conversation", "list", true, true, "viewer", "experimental", %w[org namespace agent thread_id run_id limit cursor].freeze, %w[org namespace agent thread_id].freeze), + "conversation.list_saved_messages" => OpSpec.new("conversation.list_saved_messages", "conversation", "list_saved_messages", true, true, "viewer", "experimental", %w[org namespace agent user_id conversation_id limit cursor fields].freeze, %w[org namespace agent user_id].freeze), + "conversation.save_message" => OpSpec.new("conversation.save_message", "conversation", "save_message", true, false, "writer", "experimental", %w[org namespace agent conversation_id message_id role content user_id].freeze, %w[org namespace agent conversation_id message_id role content user_id].freeze), + "conversation.saved_status" => OpSpec.new("conversation.saved_status", "conversation", "saved_status", true, true, "viewer", "experimental", %w[org namespace agent user_id conversation_id message_ids].freeze, %w[org namespace agent user_id conversation_id message_ids].freeze), + "conversation.search" => OpSpec.new("conversation.search", "conversation", "search", true, true, "viewer", "experimental", %w[org namespace agent query thread_id run_id role user_id top_k namespace_scope].freeze, %w[org namespace agent query].freeze), + "conversation.search_saved_messages" => OpSpec.new("conversation.search_saved_messages", "conversation", "search_saved_messages", true, true, "viewer", "experimental", %w[org namespace agent user_id query conversation_id role top_k search_mode lexical_weight].freeze, %w[org namespace agent user_id query].freeze), + "conversation.set_logging" => OpSpec.new("conversation.set_logging", "conversation", "set_logging", true, false, "admin", "experimental", %w[org namespace enabled].freeze, %w[org namespace enabled].freeze), + "conversation.threads" => OpSpec.new("conversation.threads", "conversation", "threads", true, true, "viewer", "stable", %w[org namespace agent window_days limit offset fields].freeze, %w[org namespace].freeze), + "conversation.unsave_message" => OpSpec.new("conversation.unsave_message", "conversation", "unsave_message", true, false, "writer", "experimental", %w[org namespace agent conversation_id message_id user_id].freeze, %w[org namespace agent conversation_id message_id user_id].freeze), + "conversation.update" => OpSpec.new("conversation.update", "conversation", "update", true, false, "writer", "experimental", %w[org namespace agent thread_id title metadata run_id].freeze, %w[org namespace agent thread_id].freeze), + "cost.agent_summary" => OpSpec.new("cost.agent_summary", "cost", "agent_summary", true, true, "viewer", "stable", %w[org namespace from_date to_date group_by agent consumer].freeze, %w[org from_date to_date].freeze), + "cost.budget_status" => OpSpec.new("cost.budget_status", "cost", "budget_status", true, true, "viewer", "stable", %w[org namespace user_id].freeze, %w[org].freeze), + "cost.record_turns" => OpSpec.new("cost.record_turns", "cost", "record_turns", true, false, "writer", "experimental", %w[org namespace agent user_id session_id consumer turns].freeze, %w[org namespace session_id turns].freeze), + "cost.summary" => OpSpec.new("cost.summary", "cost", "summary", true, true, "viewer", "stable", %w[org namespace from_date to_date group_by agent operation user_id traffic_class instance_label include_cache].freeze, %w[org from_date to_date].freeze), + "decision.chain" => OpSpec.new("decision.chain", "decision", "chain", true, true, "viewer", "experimental", %w[org namespace memory_key direction max_hops].freeze, %w[org namespace memory_key].freeze), + "decision.outcome" => OpSpec.new("decision.outcome", "decision", "outcome", false, false, "writer", "experimental", %w[org namespace memory_key realized_outcome success agent].freeze, %w[org namespace memory_key realized_outcome].freeze), + "decision.precedents" => OpSpec.new("decision.precedents", "decision", "precedents", true, true, "viewer", "experimental", %w[org namespace agent query category top_k with_outcome_only].freeze, %w[org namespace query].freeze), + "decision.record" => OpSpec.new("decision.record", "decision", "record", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id category scenario reasoning outcome alternatives confidence stage decision_maker caused_by influenced_by tags valid_at files source_class source_resource_id].freeze, %w[org namespace agent category scenario reasoning outcome].freeze), + "erasure.export" => OpSpec.new("erasure.export", "erasure", "export", true, false, "admin", "stable", %w[org scope_type scope_value requester include_tombstoned section_limit].freeze, %w[org scope_type scope_value requester].freeze), + "erasure.list" => OpSpec.new("erasure.list", "erasure", "list", true, true, "viewer", "experimental", %w[org limit status].freeze, %w[org].freeze), + "erasure.request" => OpSpec.new("erasure.request", "erasure", "request", true, false, "writer", "stable", %w[org scope_type scope_value requester urgency purge external].freeze, %w[org scope_type scope_value requester].freeze), + "erasure.status" => OpSpec.new("erasure.status", "erasure", "status", true, true, "viewer", "experimental", %w[erasure_id].freeze, %w[erasure_id].freeze), + "extraction_policy.clear" => OpSpec.new("extraction_policy.clear", "extraction_policy", "clear", true, false, "org_admin", "experimental", %w[org scope namespace].freeze, %w[org scope].freeze), + "extraction_policy.get" => OpSpec.new("extraction_policy.get", "extraction_policy", "get", true, false, "org_admin", "experimental", %w[org scope namespace].freeze, %w[org scope].freeze), + "extraction_policy.set" => OpSpec.new("extraction_policy.set", "extraction_policy", "set", true, false, "org_admin", "experimental", %w[org scope namespace policy].freeze, %w[org scope policy].freeze), + "facts.expire_by_adapter" => OpSpec.new("facts.expire_by_adapter", "facts", "expire_by_adapter", false, false, "admin", "experimental", %w[org namespace adapter_name max_confidence].freeze, %w[org namespace adapter_name].freeze), + "facts.list" => OpSpec.new("facts.list", "facts", "list", true, true, "viewer", "stable", %w[org namespace subject object relation entity limit sort_by include_sources include_source_status min_co_occur as_of provenance].freeze, %w[org namespace].freeze), + "facts.path" => OpSpec.new("facts.path", "facts", "path", true, true, "viewer", "experimental", %w[org namespace entity_a entity_b max_hops top_k_per_hop min_co_occur as_of relations labeled].freeze, %w[org namespace entity_a entity_b].freeze), + "facts.related" => OpSpec.new("facts.related", "facts", "related", true, true, "viewer", "experimental", %w[org namespace entity top_k as_of].freeze, %w[org namespace entity].freeze), + "facts.traverse" => OpSpec.new("facts.traverse", "facts", "traverse", true, true, "viewer", "stable", %w[org namespace seed_entity max_hops top_k_per_hop min_co_occur max_nodes as_of relations labeled hub_degree hub_share rank_by].freeze, %w[org namespace seed_entity].freeze), + "grants.approve" => OpSpec.new("grants.approve", "grants", "approve", true, false, "admin", "experimental", %w[org namespace subject decision role].freeze, %w[org namespace subject].freeze), + "grants.create" => OpSpec.new("grants.create", "grants", "create", true, false, "admin", "stable", %w[org namespace subject role granted_by replace].freeze, %w[org namespace subject role].freeze), + "grants.list" => OpSpec.new("grants.list", "grants", "list", true, true, "viewer", "stable", %w[org namespace limit cursor fields].freeze, %w[org namespace].freeze), + "grants.pending_for_me" => OpSpec.new("grants.pending_for_me", "grants", "pending_for_me", true, true, "viewer", "experimental", %w[org limit].freeze, %w[org].freeze), + "grants.revoke" => OpSpec.new("grants.revoke", "grants", "revoke", true, false, "admin", "experimental", %w[org namespace subject].freeze, %w[org namespace subject].freeze), + "grants.share_agent" => OpSpec.new("grants.share_agent", "grants", "share_agent", true, false, "writer", "experimental", %w[org namespace grantee role].freeze, %w[org namespace grantee].freeze), + "grants.unshare_agent" => OpSpec.new("grants.unshare_agent", "grants", "unshare_agent", true, false, "writer", "experimental", %w[org namespace grantee].freeze, %w[org namespace grantee].freeze), + "help.get" => OpSpec.new("help.get", "help", "get", true, true, "viewer", "experimental", %w[org path section anchor offset].freeze, %w[path].freeze), + "help.search" => OpSpec.new("help.search", "help", "search", true, true, "viewer", "experimental", %w[org query limit].freeze, %w[query].freeze), + "inbox.list" => OpSpec.new("inbox.list", "inbox", "list", true, true, "viewer", "experimental", %w[org namespace agent mine_everywhere limit].freeze, %w[org namespace].freeze), + "inbox.policy_list" => OpSpec.new("inbox.policy_list", "inbox", "policy_list", true, true, "viewer", "experimental", %w[org namespace agent inbox].freeze, %w[org namespace inbox].freeze), + "inbox.policy_set" => OpSpec.new("inbox.policy_set", "inbox", "policy_set", true, false, "admin", "experimental", %w[org namespace agent inbox poster kind mode require_evidence remove].freeze, %w[org namespace inbox poster mode].freeze), + "inbox.principals" => OpSpec.new("inbox.principals", "inbox", "principals", true, false, "admin", "experimental", %w[org namespace agent inbox query limit].freeze, %w[org namespace inbox].freeze), + "inbox.register" => OpSpec.new("inbox.register", "inbox", "register", true, false, "admin", "experimental", %w[org namespace agent inbox owner_agent description posters accept_disclosure default_lease_seconds max_attempts max_defers triage_escalate_after_seconds webhook_url webhook_secret_ref if_match_version].freeze, %w[org namespace inbox owner_agent].freeze), + "insights.catalog" => OpSpec.new("insights.catalog", "insights", "catalog", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "insights.query" => OpSpec.new("insights.query", "insights", "query", true, true, "viewer", "experimental", %w[org namespace sql limit].freeze, %w[org namespace sql].freeze), + "knowledge.add" => OpSpec.new("knowledge.add", "knowledge", "add", true, false, "writer", "stable", %w[org namespace source_uri content title description tags metadata original_bytes_b64 original_filename blob_content_type agent session_id source_class].freeze, %w[org namespace source_uri content].freeze), + "knowledge.bulk_add" => OpSpec.new("knowledge.bulk_add", "knowledge", "bulk_add", true, false, "writer", "stable", %w[org namespace entries agent session_id source_class].freeze, %w[org namespace entries].freeze), + "knowledge.bulk_delete" => OpSpec.new("knowledge.bulk_delete", "knowledge", "bulk_delete", true, false, "writer", "experimental", %w[org namespace source_uris].freeze, %w[org namespace source_uris].freeze), + "knowledge.dataset_approve" => OpSpec.new("knowledge.dataset_approve", "knowledge", "dataset_approve", false, false, "writer", "experimental", %w[org namespace source_uri dataset_id snapshot_id columns].freeze, %w[org namespace source_uri dataset_id snapshot_id].freeze), + "knowledge.dataset_get" => OpSpec.new("knowledge.dataset_get", "knowledge", "dataset_get", true, true, "viewer", "experimental", %w[org namespace source_uri dataset_id sample_rows].freeze, %w[org namespace source_uri].freeze), + "knowledge.dedup_list" => OpSpec.new("knowledge.dedup_list", "knowledge", "dedup_list", true, false, "admin", "experimental", %w[org namespace limit include_chunk_clusters].freeze, %w[org namespace].freeze), + "knowledge.dedup_resolve" => OpSpec.new("knowledge.dedup_resolve", "knowledge", "dedup_resolve", true, false, "admin", "experimental", %w[org namespace canonical_uri duplicate_uri decision confirm_duplicate_uri].freeze, %w[org namespace canonical_uri duplicate_uri decision confirm_duplicate_uri].freeze), + "knowledge.delete" => OpSpec.new("knowledge.delete", "knowledge", "delete", true, false, "writer", "experimental", %w[org namespace source_uri].freeze, %w[org namespace source_uri].freeze), + "knowledge.formats" => OpSpec.new("knowledge.formats", "knowledge", "formats", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "knowledge.gaps.draft" => OpSpec.new("knowledge.gaps.draft", "knowledge", "gaps_draft", true, false, "admin", "experimental", %w[org namespace gap_id].freeze, %w[org namespace gap_id].freeze), + "knowledge.gaps.list" => OpSpec.new("knowledge.gaps.list", "knowledge", "gaps_list", true, false, "admin", "experimental", %w[org namespace limit].freeze, %w[org namespace].freeze), + "knowledge.get" => OpSpec.new("knowledge.get", "knowledge", "get", true, true, "viewer", "stable", %w[org namespace source_uri include_superseded].freeze, %w[org namespace source_uri].freeze), + "knowledge.ingest" => OpSpec.new("knowledge.ingest", "knowledge", "ingest", false, false, "writer", "experimental", %w[org namespace upload_id source_uri title description tags metadata expected_revision allow_partial options agent session_id source_class].freeze, %w[org namespace upload_id source_uri].freeze), + "knowledge.ingest_cancel" => OpSpec.new("knowledge.ingest_cancel", "knowledge", "ingest_cancel", true, false, "writer", "experimental", %w[org namespace ingestion_id].freeze, %w[org namespace ingestion_id].freeze), + "knowledge.ingest_status" => OpSpec.new("knowledge.ingest_status", "knowledge", "ingest_status", true, true, "viewer", "experimental", %w[org namespace ingestion_id].freeze, %w[org namespace ingestion_id].freeze), + "knowledge.inspect" => OpSpec.new("knowledge.inspect", "knowledge", "inspect_", true, true, "viewer", "experimental", %w[org namespace sample_limit].freeze, %w[org namespace].freeze), + "knowledge.list" => OpSpec.new("knowledge.list", "knowledge", "list", true, true, "viewer", "stable", %w[org namespace namespaces tags tags_every uri_prefix include_superseded limit cursor fields].freeze, %w[org namespace].freeze), + "knowledge.move" => OpSpec.new("knowledge.move", "knowledge", "move", true, false, "writer", "experimental", %w[org namespace to_namespace source_uris].freeze, %w[org namespace to_namespace source_uris].freeze), + "knowledge.outline" => OpSpec.new("knowledge.outline", "knowledge", "outline", true, true, "viewer", "experimental", %w[org namespace source_uri section_path include_children].freeze, %w[org namespace source_uri].freeze), + "knowledge.query" => OpSpec.new("knowledge.query", "knowledge", "query", true, true, "viewer", "experimental", %w[org namespace datasets where joins group_by aggregates select order_by limit].freeze, %w[org namespace datasets].freeze), + "knowledge.query_history.add" => OpSpec.new("knowledge.query_history.add", "knowledge", "query_history_add", false, false, "admin", "experimental", %w[org namespace name host port secure user password databases cluster].freeze, %w[org namespace name host user password databases].freeze), + "knowledge.query_history.list" => OpSpec.new("knowledge.query_history.list", "knowledge", "query_history_list", true, false, "admin", "experimental", %w[fields org namespace limit].freeze, %w[org namespace].freeze), + "knowledge.query_history.remove" => OpSpec.new("knowledge.query_history.remove", "knowledge", "query_history_remove", true, false, "admin", "experimental", %w[org namespace name].freeze, %w[org namespace name].freeze), + "knowledge.reads" => OpSpec.new("knowledge.reads", "knowledge", "reads", true, true, "viewer", "experimental", %w[org namespace days source_uris].freeze, %w[org namespace].freeze), + "knowledge.restore" => OpSpec.new("knowledge.restore", "knowledge", "restore", true, false, "writer", "experimental", %w[org namespace source_uri if_revision].freeze, %w[org namespace source_uri].freeze), + "knowledge.search" => OpSpec.new("knowledge.search", "knowledge", "search", true, true, "viewer", "stable", %w[org namespace query tags since_seconds top_k namespace_scope namespaces search_mode lexical_weight narrow_spans collapse_sections uri_prefix session_ids source_classes formats block_types rerank].freeze, %w[org namespace query].freeze), + "knowledge.source.add" => OpSpec.new("knowledge.source.add", "knowledge", "source_add", false, false, "writer", "experimental", %w[org namespace name kind items links config include credential_mode credential dry_run].freeze, %w[org namespace name kind].freeze), + "knowledge.source.check" => OpSpec.new("knowledge.source.check", "knowledge", "source_check", true, false, "writer", "experimental", %w[org namespace name].freeze, %w[org namespace name].freeze), + "knowledge.source.inspect" => OpSpec.new("knowledge.source.inspect", "knowledge", "source_inspect", true, true, "viewer", "experimental", %w[org namespace name].freeze, %w[org namespace name].freeze), + "knowledge.source.list" => OpSpec.new("knowledge.source.list", "knowledge", "source_list", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "knowledge.source.parse_links" => OpSpec.new("knowledge.source.parse_links", "knowledge", "source_parse_links", true, true, "viewer", "experimental", %w[org namespace links].freeze, %w[org namespace links].freeze), + "knowledge.source.push_configure" => OpSpec.new("knowledge.source.push_configure", "knowledge", "source_push_configure", false, false, "admin", "experimental", %w[org namespace name enabled agent user_id session_id].freeze, %w[org namespace name].freeze), + "knowledge.source.push_confirm" => OpSpec.new("knowledge.source.push_confirm", "knowledge", "source_push_confirm", false, false, "admin", "experimental", %w[org namespace name generation challenge_fingerprint signing_secret].freeze, %w[org namespace name generation].freeze), + "knowledge.source.push_status" => OpSpec.new("knowledge.source.push_status", "knowledge", "source_push_status", false, false, "admin", "experimental", %w[org namespace name reveal_challenge].freeze, %w[org namespace name].freeze), + "knowledge.source.remove" => OpSpec.new("knowledge.source.remove", "knowledge", "source_remove", false, false, "writer", "experimental", %w[org namespace name confirm delete_documents].freeze, %w[org namespace name confirm].freeze), + "knowledge.source.rotate" => OpSpec.new("knowledge.source.rotate", "knowledge", "source_rotate", false, false, "admin", "experimental", %w[org namespace name credential].freeze, %w[org namespace name credential].freeze), + "knowledge.source.sync_now" => OpSpec.new("knowledge.source.sync_now", "knowledge", "source_sync_now", true, false, "writer", "experimental", %w[org namespace name full].freeze, %w[org namespace name].freeze), + "knowledge.source.update" => OpSpec.new("knowledge.source.update", "knowledge", "source_update", false, false, "writer", "experimental", %w[org namespace name add_items add_links remove_items remove_links include].freeze, %w[org namespace name].freeze), + "knowledge.synthesize" => OpSpec.new("knowledge.synthesize", "knowledge", "synthesize", true, false, "viewer", "experimental", %w[org namespace user_id source_uris datasets task window_chars max_answer_chars max_windows].freeze, %w[org namespace task].freeze), + "knowledge.update_metadata" => OpSpec.new("knowledge.update_metadata", "knowledge", "update_metadata", true, false, "writer", "experimental", %w[org namespace source_uri title description tags reindex].freeze, %w[org namespace source_uri].freeze), + "knowledge.upsert" => OpSpec.new("knowledge.upsert", "knowledge", "upsert", true, false, "writer", "experimental", %w[org namespace source_uri content title description tags metadata original_bytes_b64 original_filename blob_content_type agent session_id source_class].freeze, %w[org namespace source_uri content].freeze), + "learnings.list" => OpSpec.new("learnings.list", "learnings", "list", true, true, "viewer", "experimental", %w[org namespace status limit source_kind].freeze, %w[org namespace].freeze), + "learnings.quality" => OpSpec.new("learnings.quality", "learnings", "quality", true, true, "viewer", "experimental", %w[org namespace source_kind].freeze, %w[org].freeze), + "learnings.review" => OpSpec.new("learnings.review", "learnings", "review", true, false, "admin", "experimental", %w[org namespace candidate_id decision reason destination approver].freeze, %w[org namespace candidate_id decision].freeze), + "memory.agents_list" => OpSpec.new("memory.agents_list", "memory", "agents_list", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id].freeze, %w[org namespace].freeze), + "memory.aggregate" => OpSpec.new("memory.aggregate", "memory", "aggregate", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id agg_func agg_field group_by filter limit].freeze, %w[org namespace agent].freeze), + "memory.append_batch" => OpSpec.new("memory.append_batch", "memory", "append_batch", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id entries].freeze, %w[org namespace agent entries].freeze), + "memory.apply" => OpSpec.new("memory.apply", "memory", "apply", false, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id target action reason limit dry_run expire lock label demote].freeze, %w[org namespace agent target action reason].freeze), + "memory.ask" => OpSpec.new("memory.ask", "memory", "ask", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id query memory_type tags tags_soft tag_boost top_k bodies body_budget_tokens source_span_chars allow_synthesis reinforce reinforcement_weight max_answer_chars namespace_scope search_mode read_scope sensitivity_penalty summary_cap rrf_adaptive_lexical personalization as_of as_of_basis include_superseded precedents llm_cache depth deep_select deep_first recount token_budget personalize window_rel_floor decompose world_knowledge consistency route_prior route_prior_max_cheap mid_model mid_routes default_answer_chars digest_descent presupposition_rule set_window knowledge recent_messages observation_date gh_items_fallback].freeze, %w[org namespace query].freeze), + "memory.assign_category" => OpSpec.new("memory.assign_category", "memory", "assign_category", true, false, "writer", "experimental", %w[org namespace memory_key category_name tombstone].freeze, %w[org namespace memory_key category_name].freeze), + "memory.auto_retirements" => OpSpec.new("memory.auto_retirements", "memory", "auto_retirements", true, true, "viewer", "experimental", %w[org namespace since limit cursor].freeze, %w[org namespace].freeze), + "memory.backlinks" => OpSpec.new("memory.backlinks", "memory", "backlinks", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id memory_key limit].freeze, %w[org namespace agent memory_key].freeze), + "memory.brief" => OpSpec.new("memory.brief", "memory", "brief", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id query top_k tags].freeze, %w[org namespace agent query].freeze), + "memory.bulk_get" => OpSpec.new("memory.bulk_get", "memory", "bulk_get", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id memory_keys fields].freeze, %w[org namespace agent memory_keys].freeze), + "memory.bulk_set" => OpSpec.new("memory.bulk_set", "memory", "bulk_set", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id entries contextualize detect_updates].freeze, %w[org namespace agent entries].freeze), + "memory.clear" => OpSpec.new("memory.clear", "memory", "clear", true, false, "admin", "stable", %w[org namespace user_id agent confirm_subject].freeze, %w[org namespace confirm_subject].freeze), + "memory.consolidate" => OpSpec.new("memory.consolidate", "memory", "consolidate", false, false, "writer", "stable", %w[org namespace agent user_id session_id run_id limit similarity_threshold min_age_seconds dry_run].freeze, %w[org namespace agent].freeze), + "memory.copy_to" => OpSpec.new("memory.copy_to", "memory", "copy_to", false, false, "writer", "experimental", %w[from_org from_namespace memory_key from_agent from_user_id from_session_id to_namespace target_key target_agent rationale].freeze, %w[from_org from_namespace memory_key to_namespace].freeze), + "memory.cross_promote" => OpSpec.new("memory.cross_promote", "memory", "cross_promote", false, false, "viewer", "experimental", %w[from_org from_namespace from_memory_id to_namespace target_key target_agent rationale].freeze, %w[from_org from_namespace from_memory_id to_namespace].freeze), + "memory.dedup_collapse" => OpSpec.new("memory.dedup_collapse", "memory", "dedup_collapse", true, false, "writer", "experimental", %w[org namespace prefix dry_run limit sample].freeze, %w[org namespace].freeze), + "memory.dedup_list" => OpSpec.new("memory.dedup_list", "memory", "dedup_list", true, false, "admin", "stable", %w[org namespace limit].freeze, %w[org namespace].freeze), + "memory.dedup_resolve" => OpSpec.new("memory.dedup_resolve", "memory", "dedup_resolve", true, false, "admin", "stable", %w[org namespace canonical_id duplicate_id decision confirm_canonical_key canonical_key duplicate_key].freeze, %w[org namespace canonical_id duplicate_id decision confirm_canonical_key].freeze), + "memory.definitions.list" => OpSpec.new("memory.definitions.list", "memory", "definitions_list", true, false, "admin", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "memory.delete" => OpSpec.new("memory.delete", "memory", "delete", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id memory_key].freeze, %w[org namespace agent memory_key].freeze), + "memory.delete_version" => OpSpec.new("memory.delete_version", "memory", "delete_version", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id memory_key version].freeze, %w[org namespace agent memory_key version].freeze), + "memory.demonstrate" => OpSpec.new("memory.demonstrate", "memory", "demonstrate", true, true, "viewer", "experimental", %w[org namespace agent query k example_tag label_prefix namespace_scope min_margin max_block_chars].freeze, %w[org namespace query].freeze), + "memory.demote" => OpSpec.new("memory.demote", "memory", "demote", true, false, "admin", "experimental", %w[org namespace memory_key rationale].freeze, %w[org namespace memory_key].freeze), + "memory.digests" => OpSpec.new("memory.digests", "memory", "digests", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id limit].freeze, %w[org namespace agent].freeze), + "memory.evidence" => OpSpec.new("memory.evidence", "memory", "evidence", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id memory_key limit].freeze, %w[org namespace agent memory_key].freeze), + "memory.export_evidence" => OpSpec.new("memory.export_evidence", "memory", "export_evidence", true, true, "viewer", "stable", %w[org namespace kind session_id limit cursor include_high].freeze, %w[org namespace].freeze), + "memory.exposure_summary" => OpSpec.new("memory.exposure_summary", "memory", "exposure_summary", true, false, "admin", "experimental", %w[org namespace since_hours limit].freeze, %w[org namespace].freeze), + "memory.extraction_retry_mine" => OpSpec.new("memory.extraction_retry_mine", "memory", "extraction_retry_mine", true, false, "writer", "experimental", %w[org namespace queue_ids].freeze, %w[org namespace queue_ids].freeze), + "memory.extraction_status" => OpSpec.new("memory.extraction_status", "memory", "extraction_status", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id queue_id status limit].freeze, %w[org namespace].freeze), + "memory.extraction_status_mine" => OpSpec.new("memory.extraction_status_mine", "memory", "extraction_status_mine", true, true, "viewer", "experimental", %w[org namespace queue_ids].freeze, %w[org namespace queue_ids].freeze), + "memory.for_file" => OpSpec.new("memory.for_file", "memory", "for_file", true, true, "viewer", "stable", %w[org namespace path tags top_k token_budget include_conflicted extra_namespaces].freeze, %w[org namespace path].freeze), + "memory.get" => OpSpec.new("memory.get", "memory", "get", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id memory_key if_version include_recall_breakdown as_of fields follow].freeze, %w[org namespace agent memory_key].freeze), + "memory.get_by_id" => OpSpec.new("memory.get_by_id", "memory", "get_by_id", true, true, "viewer", "stable", %w[org memory_id as_of omit_high_value].freeze, %w[org memory_id].freeze), + "memory.health" => OpSpec.new("memory.health", "memory", "health", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id silent_after_days top_k].freeze, %w[org namespace].freeze), + "memory.history" => OpSpec.new("memory.history", "memory", "history", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id memory_key limit].freeze, %w[org namespace agent memory_key].freeze), + "memory.import" => OpSpec.new("memory.import", "memory", "import", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id entries dry_run].freeze, %w[org namespace agent entries].freeze), + "memory.import_curated" => OpSpec.new("memory.import_curated", "memory", "import_curated", false, false, "writer", "experimental", %w[org namespace content source_uri heading_level extra_tags].freeze, %w[org namespace content].freeze), + "memory.import_evidence" => OpSpec.new("memory.import_evidence", "memory", "import_evidence", false, false, "writer", "stable", %w[org namespace agent user_id chunks digests source_trace].freeze, %w[org namespace agent].freeze), + "memory.inspect" => OpSpec.new("memory.inspect", "memory", "inspect_", true, true, "viewer", "experimental", %w[org namespace subject id sample_limit window_seconds].freeze, %w[org namespace subject id].freeze), + "memory.keys" => OpSpec.new("memory.keys", "memory", "keys", true, true, "viewer", "experimental", %w[org namespace limit].freeze, %w[org namespace].freeze), + "memory.lineage" => OpSpec.new("memory.lineage", "memory", "lineage", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id memory_key scope candidate_match_window_s].freeze, %w[org namespace agent memory_key].freeze), + "memory.link" => OpSpec.new("memory.link", "memory", "link", false, false, "writer", "stable", %w[org namespace from_key to_key relation label explanation evidence confidence run_id weight tombstone].freeze, %w[org namespace from_key to_key].freeze), + "memory.list" => OpSpec.new("memory.list", "memory", "list", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id prefix memory_type source_trace limit offset count_only preview_chars sort_by quotas include_tombstoned include_duplicates include_superseded include_proposed as_of tags tags_every contains fields known_version].freeze, %w[org namespace agent].freeze), + "memory.lock" => OpSpec.new("memory.lock", "memory", "lock", false, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id memory_key mode reason until ttl_seconds locked_by].freeze, %w[org namespace agent memory_key reason].freeze), + "memory.move" => OpSpec.new("memory.move", "memory", "move", false, false, "writer", "stable", %w[org namespace agent user_id session_id run_id from_key to_key value memory_type tags entities valid_at source_resource_id keep_redirect if_match_sha256 dry_run].freeze, %w[org namespace agent from_key to_key].freeze), + "memory.outcome" => OpSpec.new("memory.outcome", "memory", "outcome", false, false, "writer", "experimental", %w[org namespace memory_id memory_key agent user_id outcome weight source].freeze, %w[org namespace outcome].freeze), + "memory.outcome_run" => OpSpec.new("memory.outcome_run", "memory", "outcome_run", false, false, "writer", "stable", %w[org namespace outcome memory_keys run_id weight source max_keys].freeze, %w[org namespace outcome].freeze), + "memory.outline" => OpSpec.new("memory.outline", "memory", "outline", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id sessions_limit hubs_limit communities_limit].freeze, %w[org namespace agent].freeze), + "memory.owner_report" => OpSpec.new("memory.owner_report", "memory", "owner_report", true, true, "viewer", "experimental", %w[org user_id namespace since_hours limit].freeze, %w[org].freeze), + "memory.pin" => OpSpec.new("memory.pin", "memory", "pin", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id memory_key memory_type value tags entities relations files confidence source_trace source_class source_resource_id ttl_seconds clear_expiry on_expire expire_reason valid_at valid_to pinned classify if_match_sha256 char_limit sensitivity dry_run proposed].freeze, %w[org namespace agent memory_key value].freeze), + "memory.promote" => OpSpec.new("memory.promote", "memory", "promote", false, false, "admin", "experimental", %w[org namespace agent user_id session_id memory_key target_key rationale approver reversible_for_days promoted_from_candidate_id approved_sha256].freeze, %w[org namespace agent memory_key].freeze), + "memory.proposal_decide" => OpSpec.new("memory.proposal_decide", "memory", "proposal_decide", true, false, "admin", "experimental", %w[org namespace memory_keys decision approved_sha256 reason].freeze, %w[org namespace memory_keys decision].freeze), + "memory.proposals" => OpSpec.new("memory.proposals", "memory", "proposals", true, true, "viewer", "experimental", %w[org namespace prefix tags only limit].freeze, %w[org namespace].freeze), + "memory.provenance" => OpSpec.new("memory.provenance", "memory", "provenance", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id memory_key].freeze, %w[org namespace agent memory_key].freeze), + "memory.recall" => OpSpec.new("memory.recall", "memory", "recall", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id query since until thread role match order top_k cursor offset max_chars read_scope].freeze, %w[org namespace agent].freeze), + "memory.record.conflicts" => OpSpec.new("memory.record.conflicts", "memory", "record_conflicts", true, true, "viewer", "experimental", %w[org namespace schema_name memory_key open_only limit].freeze, %w[org namespace].freeze), + "memory.record.history" => OpSpec.new("memory.record.history", "memory", "record_history", true, true, "viewer", "stable", %w[org namespace record_id limit].freeze, %w[org namespace record_id].freeze), + "memory.record.query" => OpSpec.new("memory.record.query", "memory", "record_query", true, true, "viewer", "stable", %w[org namespace schema_name filters predicates as_of limit].freeze, %w[org namespace schema_name].freeze), + "memory.record.write" => OpSpec.new("memory.record.write", "memory", "record_write", false, false, "writer", "stable", %w[org namespace schema_name memory_key memory_id agent user_id session_id fields valid_at valid_to].freeze, %w[org namespace schema_name fields].freeze), + "memory.redact" => OpSpec.new("memory.redact", "memory", "redact", true, false, "admin", "experimental", %w[org memory_id version reason redacted_by].freeze, %w[org memory_id version].freeze), + "memory.reindex" => OpSpec.new("memory.reindex", "memory", "reindex", true, false, "admin", "experimental", %w[org namespace limit force].freeze, %w[org namespace].freeze), + "memory.reject" => OpSpec.new("memory.reject", "memory", "reject", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id memory_key rejection_reason].freeze, %w[org namespace agent memory_key].freeze), + "memory.related" => OpSpec.new("memory.related", "memory", "related", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id memory_key top_k min_overlap].freeze, %w[org namespace agent memory_key].freeze), + "memory.resolve_orphan_duplicates" => OpSpec.new("memory.resolve_orphan_duplicates", "memory", "resolve_orphan_duplicates", true, false, "writer", "stable", %w[org namespace limit dry_run].freeze, %w[org namespace].freeze), + "memory.restore" => OpSpec.new("memory.restore", "memory", "restore", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id memory_key if_superseded_by only_if_superseded].freeze, %w[org namespace agent memory_key].freeze), + "memory.search" => OpSpec.new("memory.search", "memory", "search", true, true, "viewer", "stable", %w[org namespace agent render query memory_type tags scope namespace_scope search_mode recipe alpha include_top_n_unmatched include_tags include_usage include_duplicates include_superseded include_proposed explain legs auto_touch user_id run_id session_id session_ids exclude_keys quality_filter read_scope entity_filter category tags_soft tag_boost category_soft category_boost confidence_weight prior_cap sensitivity_penalty rrf_adaptive_lexical demote_tags reinforcement_weight recency_pool_weight reinforcement_half_life_days mention_boost ground_relative_dates reinforcement_half_life_use_scale key_match key_match_mode digest_descent role top_k key_axis bodies body_budget_tokens source_span_chars paging page recent_first anchor_first per_speaker_quota min_body_chars graph_seed diversify diversify_session_cap summary_cap chunk_cap_share floor_mode min_similarity chunk_max_share personalization observation_date rerank retrieval_budget hyde as_of as_of_basis].freeze, %w[org namespace query].freeze), + "memory.search_trace" => OpSpec.new("memory.search_trace", "memory", "search_trace", true, true, "viewer", "stable", %w[org namespace agent render query memory_type tags scope namespace_scope search_mode recipe alpha include_top_n_unmatched include_tags include_usage include_duplicates include_superseded include_proposed explain legs auto_touch user_id run_id session_id session_ids exclude_keys quality_filter read_scope entity_filter category tags_soft tag_boost category_soft category_boost confidence_weight prior_cap sensitivity_penalty rrf_adaptive_lexical demote_tags reinforcement_weight recency_pool_weight reinforcement_half_life_days mention_boost ground_relative_dates reinforcement_half_life_use_scale key_match key_match_mode digest_descent role top_k key_axis bodies body_budget_tokens source_span_chars paging page recent_first anchor_first per_speaker_quota min_body_chars graph_seed diversify diversify_session_cap summary_cap chunk_cap_share floor_mode min_similarity chunk_max_share personalization observation_date rerank retrieval_budget hyde as_of as_of_basis].freeze, %w[org namespace query].freeze), + "memory.search_trace_log" => OpSpec.new("memory.search_trace_log", "memory", "search_trace_log", true, true, "viewer", "stable", %w[org namespace since_hours agent run_id limit].freeze, %w[org namespace].freeze), + "memory.set" => OpSpec.new("memory.set", "memory", "set", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id memory_key memory_type value tags entities relations files confidence source_trace source_class source_resource_id ttl_seconds clear_expiry on_expire expire_reason valid_at valid_to pinned classify if_match_sha256 char_limit sensitivity dry_run proposed].freeze, %w[org namespace agent memory_key value].freeze), + "memory.set_from_messages" => OpSpec.new("memory.set_from_messages", "memory", "set_from_messages", false, false, "writer", "stable", %w[org namespace agent user_id session_id run_id messages extra_tags recalled_keys session_values max_tokens judge_extraction record_schema memory_key observation_date llm_cache detect_updates last_messages extraction_instructions coverage_sweep agent_learnings pipeline_steps valid_at defer].freeze, %w[org namespace agent messages].freeze), + "memory.stack" => OpSpec.new("memory.stack", "memory", "stack", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id token_budget pinned_limit recent_limit include_knowledge knowledge_top_k seed_query procedure_limit].freeze, %w[org namespace agent].freeze), + "memory.statuses" => OpSpec.new("memory.statuses", "memory", "statuses", true, true, "viewer", "experimental", %w[org namespace memory_ids].freeze, %w[org namespace memory_ids].freeze), + "memory.sweep_expired" => OpSpec.new("memory.sweep_expired", "memory", "sweep_expired", true, false, "admin", "experimental", %w[org namespace limit dry_run].freeze, %w[org namespace].freeze), + "memory.timeline" => OpSpec.new("memory.timeline", "memory", "timeline", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id entity tags memory_key_prefix since until top_k order].freeze, %w[org namespace agent].freeze), + "memory.touch" => OpSpec.new("memory.touch", "memory", "touch", false, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id memory_key memory_keys ttl_seconds clear_expiry on_expire expire_reason].freeze, %w[org namespace agent].freeze), + "memory.unlock" => OpSpec.new("memory.unlock", "memory", "unlock", true, false, "admin", "experimental", %w[org namespace agent user_id session_id run_id memory_key unlocked_by].freeze, %w[org namespace agent memory_key].freeze), + "memory.unpin" => OpSpec.new("memory.unpin", "memory", "unpin", true, false, "admin", "experimental", %w[org namespace agent user_id session_id run_id memory_key].freeze, %w[org namespace agent memory_key].freeze), + "memory.update" => OpSpec.new("memory.update", "memory", "update", false, false, "writer", "stable", %w[org namespace memory_key value agent user_id session_id run_id tags concepts confidence reason if_match_sha256 char_limit revive relations].freeze, %w[org namespace memory_key].freeze), + "memory.update_by_id" => OpSpec.new("memory.update_by_id", "memory", "update_by_id", true, false, "writer", "stable", %w[org memory_id value tags concepts if_match_sha256 char_limit revive relations].freeze, %w[org memory_id].freeze), + "memory.verify" => OpSpec.new("memory.verify", "memory", "verify", true, false, "writer", "stable", %w[org memory_id namespace agent user_id session_id memory_key revoke actor].freeze, %w[org].freeze), + "memory_schema.approve" => OpSpec.new("memory_schema.approve", "memory_schema", "approve", false, false, "admin", "experimental", %w[org namespace name decision reviewed_by].freeze, %w[org namespace name decision].freeze), + "memory_schema.list" => OpSpec.new("memory_schema.list", "memory_schema", "list", true, true, "viewer", "experimental", %w[org namespace include_proposed limit].freeze, %w[org namespace].freeze), + "memory_schema.propose" => OpSpec.new("memory_schema.propose", "memory_schema", "propose", false, false, "writer", "experimental", %w[org namespace name description fields created_by status].freeze, %w[org namespace name fields].freeze), + "memory_schema.register" => OpSpec.new("memory_schema.register", "memory_schema", "register", false, false, "admin", "stable", %w[org namespace name description fields created_by status].freeze, %w[org namespace name fields].freeze), + "mentor.brief" => OpSpec.new("mentor.brief", "mentor", "brief", true, true, "viewer", "stable", %w[org namespace agent window_seconds].freeze, %w[org namespace].freeze), + "mentor.guide" => OpSpec.new("mentor.guide", "mentor", "guide", true, true, "viewer", "experimental", %w[org part].freeze, [].freeze), + "namespace.audit" => OpSpec.new("namespace.audit", "namespace", "audit", true, true, "viewer", "stable", %w[org namespace window_seconds sample_limit].freeze, %w[org namespace].freeze), + "namespace.browse" => OpSpec.new("namespace.browse", "namespace", "browse", true, true, "viewer", "stable", %w[org query limit include_closed kinds].freeze, %w[org].freeze), + "namespace.cancel_request" => OpSpec.new("namespace.cancel_request", "namespace", "cancel_request", true, false, "viewer", "experimental", %w[org namespace subject].freeze, %w[org namespace].freeze), + "namespace.delete" => OpSpec.new("namespace.delete", "namespace", "delete", true, false, "admin", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "namespace.get" => OpSpec.new("namespace.get", "namespace", "get", true, true, "viewer", "stable", %w[org namespace].freeze, %w[org namespace].freeze), + "namespace.guide_get" => OpSpec.new("namespace.guide_get", "namespace", "guide_get", true, true, "viewer", "experimental", %w[org namespace revision].freeze, %w[org namespace].freeze), + "namespace.guide_history" => OpSpec.new("namespace.guide_history", "namespace", "guide_history", true, true, "viewer", "experimental", %w[org namespace limit].freeze, %w[org namespace].freeze), + "namespace.guide_set" => OpSpec.new("namespace.guide_set", "namespace", "guide_set", true, false, "writer", "experimental", %w[org namespace content summary expected_revision note].freeze, %w[org namespace content expected_revision].freeze), + "namespace.inventory" => OpSpec.new("namespace.inventory", "namespace", "inventory", true, true, "viewer", "experimental", %w[org namespace read_scope user_id session_id population_limit].freeze, %w[org namespace].freeze), + "namespace.join" => OpSpec.new("namespace.join", "namespace", "join", true, false, "viewer", "experimental", %w[org namespace role subject].freeze, %w[org namespace].freeze), + "namespace.leave" => OpSpec.new("namespace.leave", "namespace", "leave", true, false, "viewer", "experimental", %w[org namespace subject].freeze, %w[org namespace].freeze), + "namespace.list" => OpSpec.new("namespace.list", "namespace", "list", true, false, "org_admin", "experimental", %w[org active_only tags limit].freeze, %w[org].freeze), + "namespace.list_categories" => OpSpec.new("namespace.list_categories", "namespace", "list_categories", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "namespace.list_mine" => OpSpec.new("namespace.list_mine", "namespace", "list_mine", true, true, "viewer", "stable", %w[org subject].freeze, %w[org].freeze), + "namespace.list_ontology" => OpSpec.new("namespace.list_ontology", "namespace", "list_ontology", true, true, "viewer", "experimental", %w[org namespace kind status].freeze, %w[org namespace].freeze), + "namespace.mark_seen" => OpSpec.new("namespace.mark_seen", "namespace", "mark_seen", true, false, "viewer", "experimental", %w[org namespace subject].freeze, %w[org namespace].freeze), + "namespace.register" => OpSpec.new("namespace.register", "namespace", "register", true, false, "viewer", "stable", %w[org namespace owner_email description kind tags traffic_class active conversation_logging_enabled capture_generation_io coverage_sweep consolidation_enabled daily_cost_cap_usd daily_user_cost_cap_usd budget_alert_inbox conflict_threshold retention_days warm_days visibility requires_approval join_policy retrieval_defaults rerank_endpoint rerank_prompt_template classify_endpoint classify_prompt_template tag_registry default_conflict_policy proposal_policy code_change_policy].freeze, %w[org namespace owner_email].freeze), + "namespace.register_category" => OpSpec.new("namespace.register_category", "namespace", "register_category", false, false, "writer", "experimental", %w[org namespace name description summary].freeze, %w[org namespace name].freeze), + "namespace.register_ontology" => OpSpec.new("namespace.register_ontology", "namespace", "register_ontology", true, false, "admin", "stable", %w[org namespace kind name description status cardinality].freeze, %w[org namespace kind name].freeze), + "namespace.restore" => OpSpec.new("namespace.restore", "namespace", "restore", true, false, "viewer", "experimental", %w[org target_namespace payload rebind_agent].freeze, %w[org target_namespace payload].freeze), + "namespace.rollback" => OpSpec.new("namespace.rollback", "namespace", "rollback", false, false, "admin", "experimental", %w[org namespace as_of dry_run memory_keys max_keys].freeze, %w[org namespace as_of].freeze), + "namespace.search_categories" => OpSpec.new("namespace.search_categories", "namespace", "search_categories", true, true, "viewer", "experimental", %w[org namespace query top_k].freeze, %w[org namespace query].freeze), + "namespace.snapshot" => OpSpec.new("namespace.snapshot", "namespace", "snapshot", true, false, "admin", "experimental", %w[org namespace include_embeddings include_audit_tail_n].freeze, %w[org namespace].freeze), + "namespace.summary" => OpSpec.new("namespace.summary", "namespace", "summary", true, true, "viewer", "stable", %w[org namespace top_entities_limit activity_seconds].freeze, %w[org namespace].freeze), + "namespace.taxonomy" => OpSpec.new("namespace.taxonomy", "namespace", "taxonomy", true, true, "viewer", "stable", %w[org namespace top_n_tags top_n_entities top_n_communities].freeze, %w[org namespace].freeze), + "namespace.tune" => OpSpec.new("namespace.tune", "namespace", "tune", true, true, "viewer", "experimental", %w[org namespace window_seconds sample_limit min_rows max_category_proposals].freeze, %w[org namespace].freeze), + "namespace.validate" => OpSpec.new("namespace.validate", "namespace", "validate", true, true, "viewer", "stable", %w[org namespace sample_limit conflict_age_seconds confidence_floor embed_grace_seconds strict keys].freeze, %w[org namespace].freeze), + "observe.crystallize" => OpSpec.new("observe.crystallize", "observe", "crystallize", true, false, "writer", "stable", %w[org namespace agent user_id session_id max_observations].freeze, %w[org namespace agent].freeze), + "observe.record" => OpSpec.new("observe.record", "observe", "record", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id tool_name tool_input tool_output file_paths error tags observation_date action_type metadata observed_at].freeze, %w[org namespace agent tool_name].freeze), + "ops.capabilities" => OpSpec.new("ops.capabilities", "ops", "capabilities", true, true, "viewer", "stable", %w[org consumer].freeze, [].freeze), + "ops.health" => OpSpec.new("ops.health", "ops", "health", true, false, "org_admin", "stable", %w[org namespace].freeze, %w[org].freeze), + "ops.projection_failures.list" => OpSpec.new("ops.projection_failures.list", "ops", "projection_failures_list", true, false, "org_admin", "experimental", %w[org namespace projection status limit].freeze, %w[org].freeze), + "ops.projection_failures.resolve" => OpSpec.new("ops.projection_failures.resolve", "ops", "projection_failures_resolve", true, false, "org_admin", "experimental", %w[org failure_ids].freeze, %w[org failure_ids].freeze), + "ops.projection_failures.retry" => OpSpec.new("ops.projection_failures.retry", "ops", "projection_failures_retry", true, false, "org_admin", "experimental", %w[org namespace projection limit].freeze, %w[org].freeze), + "org.model_calls" => OpSpec.new("org.model_calls", "org", "model_calls", true, false, "org_admin", "experimental", %w[org].freeze, %w[org].freeze), + "org.set_model_calls" => OpSpec.new("org.set_model_calls", "org", "set_model_calls", true, false, "org_admin", "experimental", %w[org enabled reason locked].freeze, %w[org enabled].freeze), + "policy.check" => OpSpec.new("policy.check", "policy", "check", true, true, "viewer", "stable", %w[org namespace operation agent user_id session_id args at rules].freeze, %w[org namespace operation].freeze), + "policy.decisions" => OpSpec.new("policy.decisions", "policy", "decisions", true, true, "viewer", "experimental", %w[org namespace decision limit].freeze, %w[org namespace].freeze), + "policy.delete" => OpSpec.new("policy.delete", "policy", "delete", true, false, "admin", "experimental", %w[org namespace policy_id removed_by].freeze, %w[org namespace policy_id].freeze), + "policy.list" => OpSpec.new("policy.list", "policy", "list", true, true, "viewer", "stable", %w[org namespace include_disabled].freeze, %w[org namespace].freeze), + "policy.set" => OpSpec.new("policy.set", "policy", "set", true, false, "admin", "experimental", %w[org namespace policy_id effect actions condition description enabled mode created_by].freeze, %w[org namespace policy_id effect actions condition].freeze), + "procedure.add" => OpSpec.new("procedure.add", "procedure", "add", false, false, "writer", "stable", %w[org namespace agent user_id session_id name situation steps tags metadata graph].freeze, %w[org namespace name situation steps].freeze), + "procedure.evolve" => OpSpec.new("procedure.evolve", "procedure", "evolve", false, false, "writer", "experimental", %w[org namespace agent user_id session_id memory_key min_runs gate_mode gate_min_runs gate_margin gate_min_drop gate_alpha gate_beta gate_max_runs strike_limit gate_cost_tolerance gate_cost_min_samples].freeze, %w[org namespace memory_key].freeze), + "procedure.fork" => OpSpec.new("procedure.fork", "procedure", "fork", false, false, "writer", "experimental", %w[org namespace agent user_id session_id from_namespace from_org memory_key new_name reason].freeze, %w[org namespace from_namespace memory_key].freeze), + "procedure.list" => OpSpec.new("procedure.list", "procedure", "list", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id prefix tags limit].freeze, %w[org namespace].freeze), + "procedure.locate" => OpSpec.new("procedure.locate", "procedure", "locate", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id memory_key at recent_path hops include_notes max_notes].freeze, %w[org namespace memory_key].freeze), + "procedure.match" => OpSpec.new("procedure.match", "procedure", "match", true, true, "viewer", "stable", %w[org namespace agent user_id session_id situation top_k tags namespace_scope templates_only include_candidates include_quarantined recent_tools tool_boost utility_weight goal].freeze, %w[org namespace situation].freeze), + "procedure.record_run" => OpSpec.new("procedure.record_run", "procedure", "record_run", false, false, "writer", "experimental", %w[org namespace agent user_id session_id memory_key path ok note ts steps_taken duration_ms tokens].freeze, %w[org namespace memory_key].freeze), + "procedure.revise" => OpSpec.new("procedure.revise", "procedure", "revise", false, false, "writer", "experimental", %w[org namespace agent user_id session_id memory_key graph reason force].freeze, %w[org namespace memory_key graph].freeze), + "profile.activity" => OpSpec.new("profile.activity", "profile", "activity", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id lookback_days].freeze, %w[org namespace agent].freeze), + "profile.append" => OpSpec.new("profile.append", "profile", "append", false, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id label addition separator].freeze, %w[org namespace agent label addition].freeze), + "profile.render" => OpSpec.new("profile.render", "profile", "render", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id format labels scope read_scope].freeze, %w[org namespace agent].freeze), + "profile.replace" => OpSpec.new("profile.replace", "profile", "replace", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id label old new].freeze, %w[org namespace agent label old new].freeze), + "profile.set" => OpSpec.new("profile.set", "profile", "set", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id label value char_limit source_trace if_match_sha256].freeze, %w[org namespace agent label value].freeze), + "profile.structured" => OpSpec.new("profile.structured", "profile", "structured", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id read_scope].freeze, %w[org namespace agent].freeze), + "profile_schema.clear" => OpSpec.new("profile_schema.clear", "profile_schema", "clear", true, false, "admin", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "profile_schema.get" => OpSpec.new("profile_schema.get", "profile_schema", "get", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "profile_schema.set" => OpSpec.new("profile_schema.set", "profile_schema", "set", true, false, "admin", "experimental", %w[org namespace json_schema].freeze, %w[org namespace json_schema].freeze), + "run.begin" => OpSpec.new("run.begin", "run", "begin", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id goal user_request expected_outcome environment model consumer role metadata budget_usd budget_seconds].freeze, %w[org namespace agent goal].freeze), + "run.complete" => OpSpec.new("run.complete", "run", "complete", false, false, "writer", "stable", %w[org namespace user_id session_id run_id status final_response confidence memories_used recalled_keys outcome weight duration_ms metadata reflection retain].freeze, %w[org namespace run_id status].freeze), + "run.get" => OpSpec.new("run.get", "run", "get", true, true, "viewer", "stable", %w[org namespace run_id].freeze, %w[org namespace run_id].freeze), + "run.grade" => OpSpec.new("run.grade", "run", "grade", true, false, "writer", "experimental", %w[org namespace run_id session_id grade source reason ref].freeze, %w[org namespace grade].freeze), + "run.list" => OpSpec.new("run.list", "run", "list", true, true, "viewer", "stable", %w[org namespace agent session_id status limit offset order_by q memory_activity grade fields].freeze, %w[org namespace].freeze), + "search.query" => OpSpec.new("search.query", "search", "query", true, true, "viewer", "experimental", %w[org namespace agent query top_k tags namespace_scope recipe bodies explain live page].freeze, %w[org namespace query].freeze), + "session.brief_delete" => OpSpec.new("session.brief_delete", "session", "brief_delete", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id brief_key].freeze, %w[org namespace agent brief_key].freeze), + "session.brief_get" => OpSpec.new("session.brief_get", "session", "brief_get", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id brief_key from_session project revision include_sections full].freeze, %w[org namespace agent].freeze), + "session.brief_list" => OpSpec.new("session.brief_list", "session", "brief_list", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id project mine_only from_session limit].freeze, %w[org namespace agent].freeze), + "session.brief_save" => OpSpec.new("session.brief_save", "session", "brief_save", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id brief_key project repo branch head_sha trigger events sections event_cursor if_revision use_llm].freeze, %w[org namespace agent].freeze), + "task.accept" => OpSpec.new("task.accept", "task", "accept", false, false, "writer", "experimental", %w[org namespace agent task_id priority constraints note].freeze, %w[org namespace task_id].freeze), + "task.block" => OpSpec.new("task.block", "task", "block", false, false, "writer", "experimental", %w[org namespace agent task_id fence reason blocked_on].freeze, %w[org namespace task_id fence reason].freeze), + "task.cancel" => OpSpec.new("task.cancel", "task", "cancel", false, false, "writer", "experimental", %w[org namespace agent task_id reason fence].freeze, %w[org namespace task_id reason].freeze), + "task.claim" => OpSpec.new("task.claim", "task", "claim", false, false, "writer", "experimental", %w[org namespace agent task_id lease_seconds].freeze, %w[org namespace task_id].freeze), + "task.complete" => OpSpec.new("task.complete", "task", "complete", false, false, "writer", "experimental", %w[org namespace agent task_id fence outcome note].freeze, %w[org namespace task_id fence].freeze), + "task.counts" => OpSpec.new("task.counts", "task", "counts", true, true, "viewer", "experimental", %w[org namespace agent inbox].freeze, %w[org namespace].freeze), + "task.create" => OpSpec.new("task.create", "task", "create", true, false, "writer", "experimental", %w[org namespace agent inbox kind title brief priority disclosure not_before deadline origin parent_task_id idempotency_key from_subject].freeze, %w[org namespace inbox kind title].freeze), + "task.defer" => OpSpec.new("task.defer", "task", "defer", false, false, "writer", "experimental", %w[org namespace agent task_id fence reason resume_at].freeze, %w[org namespace task_id fence reason].freeze), + "task.fail" => OpSpec.new("task.fail", "task", "fail", false, false, "writer", "experimental", %w[org namespace agent task_id fence reason outcome].freeze, %w[org namespace task_id fence reason].freeze), + "task.get" => OpSpec.new("task.get", "task", "get", true, true, "viewer", "experimental", %w[org namespace agent task_id].freeze, %w[org namespace task_id].freeze), + "task.heartbeat" => OpSpec.new("task.heartbeat", "task", "heartbeat", true, false, "writer", "experimental", %w[org namespace agent task_id fence lease_seconds].freeze, %w[org namespace task_id fence].freeze), + "task.history" => OpSpec.new("task.history", "task", "history", true, true, "viewer", "experimental", %w[org namespace agent task_id limit].freeze, %w[org namespace task_id].freeze), + "task.list" => OpSpec.new("task.list", "task", "list", true, true, "viewer", "experimental", %w[org namespace agent inbox posted_by_me posted_by statuses kinds owner limit fields newest_first].freeze, %w[org namespace].freeze), + "task.progress" => OpSpec.new("task.progress", "task", "progress", false, false, "writer", "experimental", %w[org namespace agent task_id fence note].freeze, %w[org namespace task_id fence note].freeze), + "task.pull" => OpSpec.new("task.pull", "task", "pull", false, false, "writer", "experimental", %w[org namespace agent inbox kinds limit wait_seconds lease_seconds status].freeze, %w[org namespace inbox].freeze), + "task.reassign" => OpSpec.new("task.reassign", "task", "reassign", false, false, "writer", "experimental", %w[org namespace agent task_id to_inbox reason].freeze, %w[org namespace task_id to_inbox reason].freeze), + "task.reopen" => OpSpec.new("task.reopen", "task", "reopen", false, false, "writer", "experimental", %w[org namespace agent task_id reason fence].freeze, %w[org namespace task_id reason].freeze), + "task.resume" => OpSpec.new("task.resume", "task", "resume", false, false, "writer", "experimental", %w[org namespace agent task_id note].freeze, %w[org namespace task_id].freeze), + "task.unblock" => OpSpec.new("task.unblock", "task", "unblock", false, false, "writer", "experimental", %w[org namespace agent task_id note].freeze, %w[org namespace task_id].freeze), + "task.update" => OpSpec.new("task.update", "task", "update", false, false, "writer", "experimental", %w[org namespace agent task_id if_match_version title brief priority deadline not_before clear_deadline clear_not_before note].freeze, %w[org namespace task_id if_match_version].freeze), + "task.updates" => OpSpec.new("task.updates", "task", "updates", true, true, "viewer", "experimental", %w[org namespace agent since_seq inbox limit wait_seconds from_subject].freeze, %w[org namespace].freeze), + "task.wont_do" => OpSpec.new("task.wont_do", "task", "wont_do", false, false, "writer", "experimental", %w[org namespace agent task_id reason fence].freeze, %w[org namespace task_id reason].freeze), + "tracker.answer" => OpSpec.new("tracker.answer", "tracker", "answer", true, true, "viewer", "experimental", %w[org namespace question anchors limit explain_only].freeze, %w[namespace].freeze), + "tracker.binding" => OpSpec.new("tracker.binding", "tracker", "binding", true, true, "viewer", "experimental", %w[org namespace].freeze, %w[namespace].freeze), + "tracker.component" => OpSpec.new("tracker.component", "tracker", "component", true, true, "viewer", "experimental", %w[org namespace component limit].freeze, %w[namespace component].freeze), + "tracker.contract" => OpSpec.new("tracker.contract", "tracker", "contract", true, true, "viewer", "experimental", %w[org database].freeze, %w[org].freeze), + "tracker.duplicate_check" => OpSpec.new("tracker.duplicate_check", "tracker", "duplicate_check", true, true, "viewer", "experimental", %w[org namespace title body frames component version mentions paths symbols issue_number top_k as_of namespaces related_prs rerank].freeze, %w[namespace].freeze), + "tracker.flaky" => OpSpec.new("tracker.flaky", "tracker", "flaky", true, true, "viewer", "experimental", %w[org namespace test_name limit include_signal window_days].freeze, %w[namespace test_name].freeze), + "tracker.item" => OpSpec.new("tracker.item", "tracker", "item", true, true, "viewer", "experimental", %w[org namespace numbers].freeze, %w[namespace numbers].freeze), + "tracker.links" => OpSpec.new("tracker.links", "tracker", "links", true, true, "viewer", "experimental", %w[org namespace issue_number pr_number limit include_record].freeze, %w[namespace].freeze), + "tracker.release" => OpSpec.new("tracker.release", "tracker", "release", true, true, "viewer", "experimental", %w[org namespace version].freeze, %w[namespace version].freeze), + "tracker.similar" => OpSpec.new("tracker.similar", "tracker", "similar", true, true, "viewer", "experimental", %w[org namespace text issue_number frames kinds top_k legs].freeze, %w[namespace].freeze), + "tracker.source.add" => OpSpec.new("tracker.source.add", "tracker", "source_add", false, false, "viewer", "experimental", %w[org name host port secure database user password namespaces mapping dry_run].freeze, %w[org name host database user password namespaces].freeze), + "tracker.source.check" => OpSpec.new("tracker.source.check", "tracker", "source_check", true, true, "viewer", "experimental", %w[org name].freeze, %w[org name].freeze), + "tracker.source.inspect" => OpSpec.new("tracker.source.inspect", "tracker", "source_inspect", true, true, "viewer", "experimental", %w[org name host port secure database user password repos].freeze, %w[org].freeze), + "tracker.source.list" => OpSpec.new("tracker.source.list", "tracker", "source_list", true, true, "viewer", "experimental", %w[org fresh].freeze, %w[org].freeze), + "tracker.source.remove" => OpSpec.new("tracker.source.remove", "tracker", "source_remove", true, false, "viewer", "experimental", %w[org name confirm].freeze, %w[org name confirm].freeze), + "tracker.source.rotate" => OpSpec.new("tracker.source.rotate", "tracker", "source_rotate", false, false, "viewer", "experimental", %w[org name user password].freeze, %w[org name user password].freeze), + "tracker.source.set_mapping" => OpSpec.new("tracker.source.set_mapping", "tracker", "source_set_mapping", true, false, "viewer", "experimental", %w[org name mapping dry_run].freeze, %w[org name].freeze), + "tracker.test_signal" => OpSpec.new("tracker.test_signal", "tracker", "test_signal", true, true, "viewer", "experimental", %w[org namespace test_name window_days code_namespace include_churn pr_number include_smells].freeze, %w[namespace test_name].freeze), + "ui.vitals" => OpSpec.new("ui.vitals", "ui", "vitals", true, false, "viewer", "experimental", %w[org namespace agent route lcp_ms long_task_ms inp_ms dom_nodes api_calls api_ms build cold].freeze, %w[org namespace route].freeze), + "webhook.deliveries" => OpSpec.new("webhook.deliveries", "webhook", "deliveries", true, false, "admin", "experimental", %w[org namespace webhook_id status limit].freeze, %w[org namespace].freeze), + "webhook.list" => OpSpec.new("webhook.list", "webhook", "list", true, false, "admin", "experimental", %w[org namespace].freeze, %w[org namespace].freeze), + "webhook.register" => OpSpec.new("webhook.register", "webhook", "register", true, false, "admin", "experimental", %w[org namespace url secret_ref events].freeze, %w[org namespace url secret_ref].freeze), + "webhook.remove" => OpSpec.new("webhook.remove", "webhook", "remove", true, false, "admin", "experimental", %w[org namespace webhook_id].freeze, %w[org namespace webhook_id].freeze), + "working_memory.append" => OpSpec.new("working_memory.append", "working_memory", "append", false, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id block_key addition separator].freeze, %w[org namespace agent addition].freeze), + "working_memory.delete" => OpSpec.new("working_memory.delete", "working_memory", "delete", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id block_key].freeze, %w[org namespace agent].freeze), + "working_memory.get" => OpSpec.new("working_memory.get", "working_memory", "get", true, true, "viewer", "experimental", %w[org namespace agent user_id session_id run_id block_key].freeze, %w[org namespace agent].freeze), + "working_memory.render" => OpSpec.new("working_memory.render", "working_memory", "render", true, true, "viewer", "stable", %w[org namespace agent user_id session_id run_id block_keys format limit].freeze, %w[org namespace agent].freeze), + "working_memory.replace" => OpSpec.new("working_memory.replace", "working_memory", "replace", true, false, "writer", "experimental", %w[org namespace agent user_id session_id run_id block_key old new].freeze, %w[org namespace agent old].freeze), + "working_memory.set" => OpSpec.new("working_memory.set", "working_memory", "set", true, false, "writer", "stable", %w[org namespace agent user_id session_id run_id block_key content char_limit].freeze, %w[org namespace agent].freeze), + }.freeze + + # The `admin.*` operations. + class AdminOps < OpGroup + # `admin.users` (org_admin, writes, Idempotency-Key, experimental). + # Required: org. + def users(body = nil, request_options: nil, **fields) + call_op("admin.users", body, fields, request_options) + end + end + + # The `agents.*` operations. + class AgentsOps < OpGroup + # `agents.connected` (viewer, read-only). + # Required: org. + def connected(body = nil, request_options: nil, **fields) + call_op("agents.connected", body, fields, request_options) + end + end + + # The `assistant.*` operations. + class AssistantOps < OpGroup + # `assistant.ask` (viewer, writes, experimental). + # Required: org, namespace, question. + def ask(body = nil, request_options: nil, **fields) + call_op("assistant.ask", body, fields, request_options) + end + end + + # The `audit.*` operations. + class AuditOps < OpGroup + # `audit.list` (viewer, read-only, experimental). + # Required: org. + def list(body = nil, request_options: nil, **fields) + call_op("audit.list", body, fields, request_options) + end + end + + # The `blacklist.*` operations. + class BlacklistOps < OpGroup + # `blacklist.add` (writer, writes, Idempotency-Key, experimental). + # Refuse future memory writes whose value matches a pattern. + # Required: org, namespace, pattern. + def add(body = nil, request_options: nil, **fields) + call_op("blacklist.add", body, fields, request_options) + end + + # `blacklist.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("blacklist.list", body, fields, request_options) + end + + # `blacklist.remove` (admin, writes, Idempotency-Key, experimental). + # Required: org, pattern_id. + def remove(body = nil, request_options: nil, **fields) + call_op("blacklist.remove", body, fields, request_options) + end + + # `blacklist.sweep` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, pattern_id. + def sweep(body = nil, request_options: nil, **fields) + call_op("blacklist.sweep", body, fields, request_options) + end + end + + # The `calibration.*` operations. + class CalibrationOps < OpGroup + # `calibration.get` (viewer, read-only, experimental). + # Required: org, namespace. + def get(body = nil, request_options: nil, **fields) + call_op("calibration.get", body, fields, request_options) + end + end + + # The `code.*` operations. + class CodeOps < OpGroup + # `code.ask` (viewer, read-only). + # Required: question. + def ask(body = nil, request_options: nil, **fields) + call_op("code.ask", body, fields, request_options) + end + + # `code.backport_gap` (viewer, read-only, experimental). + # Which release branches still carry the bug this fix removed, and the exact PR to + def backport_gap(body = nil, request_options: nil, **fields) + call_op("code.backport_gap", body, fields, request_options) + end + + # `code.backport_gaps` (viewer, read-only, experimental). + # The set-wide backport report: which merged fixes labelled for + def backport_gaps(body = nil, request_options: nil, **fields) + call_op("code.backport_gaps", body, fields, request_options) + end + + # `code.bisect_candidates` (viewer, read-only, experimental). + # Rank PRs that may have introduced a bug; Loom does not test or reproduce it. + def bisect_candidates(body = nil, request_options: nil, **fields) + call_op("code.bisect_candidates", body, fields, request_options) + end + + # `code.blame_range` (viewer, read-only, experimental). + # Which merged PRs last touched these lines, between release A and B? + # Required: path, start_line, end_line. + def blame_range(body = nil, request_options: nil, **fields) + call_op("code.blame_range", body, fields, request_options) + end + + # `code.calibrate` (admin, writes). + def calibrate(body = nil, request_options: nil, **fields) + call_op("code.calibrate", body, fields, request_options) + end + + # `code.callees` (viewer, read-only, experimental). + def callees(body = nil, request_options: nil, **fields) + call_op("code.callees", body, fields, request_options) + end + + # `code.callers` (viewer, read-only). + def callers(body = nil, request_options: nil, **fields) + call_op("code.callers", body, fields, request_options) + end + + # `code.context_pack` (viewer, read-only). + def context_pack(body = nil, request_options: nil, **fields) + call_op("code.context_pack", body, fields, request_options) + end + + # `code.context_packs` (viewer, read-only). + def context_packs(body = nil, request_options: nil, **fields) + call_op("code.context_packs", body, fields, request_options) + end + + # `code.conventions` (viewer, read-only, experimental). + # The repository's recurring maintainer checks as facts over one PR's + def conventions(body = nil, request_options: nil, **fields) + call_op("code.conventions", body, fields, request_options) + end + + # `code.coverage` (viewer, read-only). + def coverage(body = nil, request_options: nil, **fields) + call_op("code.coverage", body, fields, request_options) + end + + # `code.coverage.unwatch` (viewer, writes, Idempotency-Key). + # Required: commit, inbox. + def coverage_unwatch(body = nil, request_options: nil, **fields) + call_op("code.coverage.unwatch", body, fields, request_options) + end + + # `code.coverage.watch` (viewer, writes, Idempotency-Key). + # Required: commit, inbox. + def coverage_watch(body = nil, request_options: nil, **fields) + call_op("code.coverage.watch", body, fields, request_options) + end + + # `code.coverage_claim` (viewer, read-only, experimental). + # Is this already tested? One subject — a symbol name (a C++ symbol or a SQL-level + def coverage_claim(body = nil, request_options: nil, **fields) + call_op("code.coverage_claim", body, fields, request_options) + end + + # `code.enclosing` (viewer, read-only). + # Batched `path:line` -> enclosing function. Built for the grep shim: + # Required: locations. + def enclosing(body = nil, request_options: nil, **fields) + call_op("code.enclosing", body, fields, request_options) + end + + # `code.examples` (viewer, read-only, experimental). + def examples(body = nil, request_options: nil, **fields) + call_op("code.examples", body, fields, request_options) + end + + # `code.files` (viewer, read-only, experimental). + # Which indexed files have this NAME — an rg-style glob + def files(body = nil, request_options: nil, **fields) + call_op("code.files", body, fields, request_options) + end + + # `code.first_build` (viewer, read-only, experimental). + # Which CI build first carried this commit? One subject — a commit sha (7–40 hex) + def first_build(body = nil, request_options: nil, **fields) + call_op("code.first_build", body, fields, request_options) + end + + # `code.grep` (viewer, read-only). + # Exact-match lookup over the indexed corpus. Unlike shell grep, the + # Required: pattern. + def grep(body = nil, request_options: nil, **fields) + call_op("code.grep", body, fields, request_options) + end + + # `code.history` (viewer, read-only). + def history(body = nil, request_options: nil, **fields) + call_op("code.history", body, fields, request_options) + end + + # `code.impact` (viewer, read-only). + # Symbol-shaped (name/symbol_id) or diff-shaped (files/diff) blast + def impact(body = nil, request_options: nil, **fields) + call_op("code.impact", body, fields, request_options) + end + + # `code.index_errors` (viewer, read-only). + def index_errors(body = nil, request_options: nil, **fields) + call_op("code.index_errors", body, fields, request_options) + end + + # `code.index_status` (viewer, read-only). + def index_status(body = nil, request_options: nil, **fields) + call_op("code.index_status", body, fields, request_options) + end + + # `code.map` (viewer, read-only, experimental). + def map(body = nil, request_options: nil, **fields) + call_op("code.map", body, fields, request_options) + end + + # `code.outcome` (viewer, writes, Idempotency-Key). + # Required: action. + def outcome(body = nil, request_options: nil, **fields) + call_op("code.outcome", body, fields, request_options) + end + + # `code.outline` (viewer, read-only, experimental). + # "What is in this file?" — the question a whole-file read answers at + # Required: path. + def outline(body = nil, request_options: nil, **fields) + call_op("code.outline", body, fields, request_options) + end + + # `code.path_guards` (viewer, read-only, experimental). + # The conditions that stand on the call path from `from_symbol` to + # Required: from_symbol, to_symbol. + def path_guards(body = nil, request_options: nil, **fields) + call_op("code.path_guards", body, fields, request_options) + end + + # `code.pr_check` (viewer, read-only, experimental). + # A PR draft asks whether a PR like it already exists. Every field is + def pr_check(body = nil, request_options: nil, **fields) + call_op("code.pr_check", body, fields, request_options) + end + + # `code.recent_commits` (viewer, read-only). + def recent_commits(body = nil, request_options: nil, **fields) + call_op("code.recent_commits", body, fields, request_options) + end + + # `code.refresh` (writer, writes). + # CI calls this right after a merge lands: run one ingest pass now + def refresh(body = nil, request_options: nil, **fields) + call_op("code.refresh", body, fields, request_options) + end + + # `code.reindex` (admin, writes, experimental). + # Required: git_head. + def reindex(body = nil, request_options: nil, **fields) + call_op("code.reindex", body, fields, request_options) + end + + # `code.repo.add` (viewer, writes). + # Add a repository's branch as a new read-only index. Any signed-in person of the + # Required: org, repo. + def repo_add(body = nil, request_options: nil, **fields) + call_op("code.repo.add", body, fields, request_options) + end + + # `code.repo.add_branch` (admin, writes). + # Index another branch of a repository the caller maintains. `namespace` is any + # Required: org, namespace, branch. + def repo_add_branch(body = nil, request_options: nil, **fields) + call_op("code.repo.add_branch", body, fields, request_options) + end + + # `code.repo.remote_branches` (viewer, read-only). + # What a Git remote shows before anything is written — every branch with + # Required: org, repo. + def repo_remote_branches(body = nil, request_options: nil, **fields) + call_op("code.repo.remote_branches", body, fields, request_options) + end + + # `code.repo.remove` (admin, writes, Idempotency-Key). + # Retire a repository index a person added. `confirm` must equal the namespace. The + # Required: org, namespace. + def repo_remove(body = nil, request_options: nil, **fields) + call_op("code.repo.remove", body, fields, request_options) + end + + # `code.repo.set_access` (admin, writes, Idempotency-Key, experimental). + # A maintainer sets a repository's access — its classification (`standard` | + # Required: org, namespace, classification, join_policy. + def repo_set_access(body = nil, request_options: nil, **fields) + call_op("code.repo.set_access", body, fields, request_options) + end + + # `code.repo.set_source` (admin, writes, Idempotency-Key, experimental). + # A maintainer sets the trackers this repository reads (records of issues, PRs, + # Required: org, namespace, tracker_namespaces. + def repo_set_source(body = nil, request_options: nil, **fields) + call_op("code.repo.set_source", body, fields, request_options) + end + + # `code.repos` (viewer, read-only). + # Lists the code namespaces (repo@branch entries) configured on this + def repos(body = nil, request_options: nil, **fields) + call_op("code.repos", body, fields, request_options) + end + + # `code.review_brief` (viewer, read-only, experimental). + # A merged PR's review brief: the point read of what the ingest built at merge — + def review_brief(body = nil, request_options: nil, **fields) + call_op("code.review_brief", body, fields, request_options) + end + + # `code.scip_ingest` (writer, writes, Idempotency-Key). + # Required: batch_id, seq, total_parts, payload. + def scip_ingest(body = nil, request_options: nil, **fields) + call_op("code.scip_ingest", body, fields, request_options) + end + + # `code.scip_status` (viewer, read-only). + # Required: batch_id. + def scip_status(body = nil, request_options: nil, **fields) + call_op("code.scip_status", body, fields, request_options) + end + + # `code.search` (viewer, read-only). + # Required: query. + def search(body = nil, request_options: nil, **fields) + call_op("code.search", body, fields, request_options) + end + + # `code.setting_facts` (viewer, read-only, experimental). + # One ClickHouse setting, the four places that define it: its + # Required: name. + def setting_facts(body = nil, request_options: nil, **fields) + call_op("code.setting_facts", body, fields, request_options) + end + + # `code.symbol` (viewer, read-only). + def symbol(body = nil, request_options: nil, **fields) + call_op("code.symbol", body, fields, request_options) + end + + # `code.symbol_history` (viewer, read-only, experimental). + # The regression history of one function: the merged PRs that touched it (with + def symbol_history(body = nil, request_options: nil, **fields) + call_op("code.symbol_history", body, fields, request_options) + end + + # `code.test_gate` (viewer, read-only, experimental). + # The pre-PR question in one call: for THIS change, which tests must + def test_gate(body = nil, request_options: nil, **fields) + call_op("code.test_gate", body, fields, request_options) + end + + # `code.test_home` (viewer, read-only, experimental). + # Where does a new test case belong? A dedup fingerprint — + def test_home(body = nil, request_options: nil, **fields) + call_op("code.test_home", body, fields, request_options) + end + + # `code.tests_for` (viewer, read-only, experimental). + # Which stateless tests carry EVERY named facet: the tests that `SET` a setting, + # Required: facets. + def tests_for(body = nil, request_options: nil, **fields) + call_op("code.tests_for", body, fields, request_options) + end + + # `code.trace` (viewer, read-only). + # Paste a stack trace / backtrace; get each frame resolved to its + # Required: trace. + def trace(body = nil, request_options: nil, **fields) + call_op("code.trace", body, fields, request_options) + end + + # `code.verify` (viewer, read-only). + # Verify one closed-form claim against the index and return a + # Required: kind, subject. + def verify(body = nil, request_options: nil, **fields) + call_op("code.verify", body, fields, request_options) + end + + # `code.verify_citations` (viewer, read-only, experimental). + # Every citation a draft carries, resolved against the index before + # Required: text. + def verify_citations(body = nil, request_options: nil, **fields) + call_op("code.verify_citations", body, fields, request_options) + end + end + + # The `collection.*` operations. + class CollectionOps < OpGroup + # `collection.create` (viewer, writes, Idempotency-Key, experimental). + # Create a collection: a namespace read and written only through grants. + # Required: org. + def create(body = nil, request_options: nil, **fields) + call_op("collection.create", body, fields, request_options) + end + + # `collection.delete` (admin, writes, Idempotency-Key, experimental). + # Delete a collection with what it holds: a purging erasure of the + # Required: org, namespace. + def delete(body = nil, request_options: nil, **fields) + call_op("collection.delete", body, fields, request_options) + end + + # `collection.list` (viewer, read-only, experimental). + # List the collections the caller can read, by name. + # Required: org. + def list(body = nil, request_options: nil, **fields) + call_op("collection.list", body, fields, request_options) + end + + # `collection.move` (admin, writes, Idempotency-Key, experimental). + # Put a collection under another one, or detach it. + # Required: org, namespace. + def move(body = nil, request_options: nil, **fields) + call_op("collection.move", body, fields, request_options) + end + end + + # The `conflicts.*` operations. + class ConflictsOps < OpGroup + # `conflicts.allowlist_list` (viewer, read-only, experimental). + # Required: org, namespace. + def allowlist_list(body = nil, request_options: nil, **fields) + call_op("conflicts.allowlist_list", body, fields, request_options) + end + + # `conflicts.allowlist_remove` (admin, writes, Idempotency-Key, experimental). + # Revoke an allow decision; the pair will re-flag on future writes. + # Required: org, namespace, memory_key_a, memory_key_b. + def allowlist_remove(body = nil, request_options: nil, **fields) + call_op("conflicts.allowlist_remove", body, fields, request_options) + end + + # `conflicts.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("conflicts.list", body, fields, request_options) + end + + # `conflicts.propose_revision` (viewer, read-only, experimental). + # Required: org, namespace, memory_id. + def propose_revision(body = nil, request_options: nil, **fields) + call_op("conflicts.propose_revision", body, fields, request_options) + end + + # `conflicts.resolve` (admin, writes, Idempotency-Key). + # Required: org, namespace, memory_id, decision. + def resolve(body = nil, request_options: nil, **fields) + call_op("conflicts.resolve", body, fields, request_options) + end + end + + # The `connection.*` operations. + class ConnectionOps < OpGroup + # `connection.disconnect` (viewer, writes, Idempotency-Key, experimental). + # Disconnect the caller's own provider account and stop its connected sources. + # Required: org, kind. + def disconnect(body = nil, request_options: nil, **fields) + call_op("connection.disconnect", body, fields, request_options) + end + + # `connection.list` (viewer, read-only, experimental). + # List the signed-in caller's own connected provider accounts. + # Required: org. + def list(body = nil, request_options: nil, **fields) + call_op("connection.list", body, fields, request_options) + end + end + + # The `consolidations.*` operations. + class ConsolidationsOps < OpGroup + # `consolidations.list` (viewer, read-only, experimental). + # Namespace-scoped consolidation-run history. agent + user_id are + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("consolidations.list", body, fields, request_options) + end + end + + # The `context.*` operations. + class ContextOps < OpGroup + # `context.fetch` (viewer, read-only, experimental). + # Required: org, namespace, agent, blob_key. + def fetch(body = nil, request_options: nil, **fields) + call_op("context.fetch", body, fields, request_options) + end + + # `context.offload` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, content. + def offload(body = nil, request_options: nil, **fields) + call_op("context.offload", body, fields, request_options) + end + + # `context.pack` (viewer, read-only). + # Required: org, namespace, agent. + def pack(body = nil, request_options: nil, **fields) + call_op("context.pack", body, fields, request_options) + end + end + + # The `conversation.*` operations. + class ConversationOps < OpGroup + # `conversation.append` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent, thread_id, role, content. + def append(body = nil, request_options: nil, **fields) + call_op("conversation.append", body, fields, request_options) + end + + # `conversation.compact` (writer, writes, Idempotency-Key, experimental). + # Summarize old turns into one embedded system turn and tombstone the originals. + # Required: org, namespace, agent, thread_id. + def compact(body = nil, request_options: nil, **fields) + call_op("conversation.compact", body, fields, request_options) + end + + # `conversation.create` (writer, writes, Idempotency-Key, experimental). + # Open a thread container. Optional — append creates the thread on + # Required: org, namespace, agent, thread_id. + def create(body = nil, request_options: nil, **fields) + call_op("conversation.create", body, fields, request_options) + end + + # `conversation.delete` (admin, writes, Idempotency-Key, experimental). + # Soft-delete one thread: its messages, thread row and embeddings no other agent holds. + # Required: org, namespace, agent, thread_id, confirm_thread_id. + def delete(body = nil, request_options: nil, **fields) + call_op("conversation.delete", body, fields, request_options) + end + + # `conversation.get` (viewer, read-only, experimental). + # Fetch one thread by id: thread metadata + optional messages. + # Required: org, namespace, agent, thread_id. + def get(body = nil, request_options: nil, **fields) + call_op("conversation.get", body, fields, request_options) + end + + # `conversation.list` (viewer, read-only, experimental). + # Required: org, namespace, agent, thread_id. + def list(body = nil, request_options: nil, **fields) + call_op("conversation.list", body, fields, request_options) + end + + # `conversation.list_saved_messages` (viewer, read-only, experimental). + # Page through the messages a user saved, newest first, with no query: the + # Required: org, namespace, agent, user_id. + def list_saved_messages(body = nil, request_options: nil, **fields) + call_op("conversation.list_saved_messages", body, fields, request_options) + end + + # `conversation.save_message` (writer, writes, Idempotency-Key, experimental). + # Save one chat message a user picked for search, whether or not the + # Required: org, namespace, agent, conversation_id, message_id, role, content, user_id. + def save_message(body = nil, request_options: nil, **fields) + call_op("conversation.save_message", body, fields, request_options) + end + + # `conversation.saved_status` (viewer, read-only, experimental). + # Which of a conversation's messages a user has saved, in one call: a chat + # Required: org, namespace, agent, user_id, conversation_id, message_ids. + def saved_status(body = nil, request_options: nil, **fields) + call_op("conversation.saved_status", body, fields, request_options) + end + + # `conversation.search` (viewer, read-only, experimental). + # Rank conversation messages by embedding similarity to `query`. + # Required: org, namespace, agent, query. + def search(body = nil, request_options: nil, **fields) + call_op("conversation.search", body, fields, request_options) + end + + # `conversation.search_saved_messages` (viewer, read-only, experimental). + # Hybrid search over only the messages one user saved with + # Required: org, namespace, agent, user_id, query. + def search_saved_messages(body = nil, request_options: nil, **fields) + call_op("conversation.search_saved_messages", body, fields, request_options) + end + + # `conversation.set_logging` (admin, writes, Idempotency-Key, experimental). + # Toggle whether this namespace records conversation transcripts. When + # Required: org, namespace, enabled. + def set_logging(body = nil, request_options: nil, **fields) + call_op("conversation.set_logging", body, fields, request_options) + end + + # `conversation.threads` (viewer, read-only). + # Required: org, namespace. + def threads(body = nil, request_options: nil, **fields) + call_op("conversation.threads", body, fields, request_options) + end + + # `conversation.unsave_message` (writer, writes, Idempotency-Key, experimental). + # Withdraw one message from a user's saved-message search. + # Required: org, namespace, agent, conversation_id, message_id, user_id. + def unsave_message(body = nil, request_options: nil, **fields) + call_op("conversation.unsave_message", body, fields, request_options) + end + + # `conversation.update` (writer, writes, Idempotency-Key, experimental). + # Update one thread's title/metadata/run_id. Identity + # Required: org, namespace, agent, thread_id. + def update(body = nil, request_options: nil, **fields) + call_op("conversation.update", body, fields, request_options) + end + end + + # The `cost.*` operations. + class CostOps < OpGroup + # `cost.agent_summary` (viewer, read-only). + # The coding agent's own spend (loom.agent_turn_usage) + # Required: org, from_date, to_date. + def agent_summary(body = nil, request_options: nil, **fields) + call_op("cost.agent_summary", body, fields, request_options) + end + + # `cost.budget_status` (viewer, read-only). + # Required: org. + def budget_status(body = nil, request_options: nil, **fields) + call_op("cost.budget_status", body, fields, request_options) + end + + # `cost.record_turns` (writer, writes, Idempotency-Key, experimental). + # The coding agent's own spend for one session, a batch of turns per + # Required: org, namespace, session_id, turns. + def record_turns(body = nil, request_options: nil, **fields) + call_op("cost.record_turns", body, fields, request_options) + end + + # `cost.summary` (viewer, read-only). + # Cost rollup over a date window. + # Required: org, from_date, to_date. + def summary(body = nil, request_options: nil, **fields) + call_op("cost.summary", body, fields, request_options) + end + end + + # The `decision.*` operations. + class DecisionOps < OpGroup + # `decision.chain` (viewer, read-only, experimental). + # Required: org, namespace, memory_key. + def chain(body = nil, request_options: nil, **fields) + call_op("decision.chain", body, fields, request_options) + end + + # `decision.outcome` (writer, writes, experimental). + # Required: org, namespace, memory_key, realized_outcome. + def outcome(body = nil, request_options: nil, **fields) + call_op("decision.outcome", body, fields, request_options) + end + + # `decision.precedents` (viewer, read-only, experimental). + # Required: org, namespace, query. + def precedents(body = nil, request_options: nil, **fields) + call_op("decision.precedents", body, fields, request_options) + end + + # `decision.record` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, category, scenario, reasoning, outcome. + def record(body = nil, request_options: nil, **fields) + call_op("decision.record", body, fields, request_options) + end + end + + # The `erasure.*` operations. + class ErasureOps < OpGroup + # `erasure.export` (admin, writes, Idempotency-Key). + # Required: org, scope_type, scope_value, requester. + def export(body = nil, request_options: nil, **fields) + call_op("erasure.export", body, fields, request_options) + end + + # `erasure.list` (viewer, read-only, experimental). + # Required: org. + def list(body = nil, request_options: nil, **fields) + call_op("erasure.list", body, fields, request_options) + end + + # `erasure.request` (writer, writes, Idempotency-Key). + # Required: org, scope_type, scope_value, requester. + def request(body = nil, request_options: nil, **fields) + call_op("erasure.request", body, fields, request_options) + end + + # `erasure.status` (viewer, read-only, experimental). + # Required: erasure_id. + def status(body = nil, request_options: nil, **fields) + call_op("erasure.status", body, fields, request_options) + end + end + + # The `extraction_policy.*` operations. + class ExtractionPolicyOps < OpGroup + # `extraction_policy.clear` (org_admin, writes, Idempotency-Key, experimental). + # Required: org, scope. + def clear(body = nil, request_options: nil, **fields) + call_op("extraction_policy.clear", body, fields, request_options) + end + + # `extraction_policy.get` (org_admin, writes, Idempotency-Key, experimental). + # Required: org, scope. + def get(body = nil, request_options: nil, **fields) + call_op("extraction_policy.get", body, fields, request_options) + end + + # `extraction_policy.set` (org_admin, writes, Idempotency-Key, experimental). + # Required: org, scope, policy. + def set(body = nil, request_options: nil, **fields) + call_op("extraction_policy.set", body, fields, request_options) + end + end + + # The `facts.*` operations. + class FactsOps < OpGroup + # `facts.expire_by_adapter` (admin, writes, experimental). + # Tombstone graph-level triples emitted by a specific extractor + # Required: org, namespace, adapter_name. + def expire_by_adapter(body = nil, request_options: nil, **fields) + call_op("facts.expire_by_adapter", body, fields, request_options) + end + + # `facts.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("facts.list", body, fields, request_options) + end + + # `facts.path` (viewer, read-only, experimental). + # Find how two entities are connected: a bounded bidirectional + # Required: org, namespace, entity_a, entity_b. + def path(body = nil, request_options: nil, **fields) + call_op("facts.path", body, fields, request_options) + end + + # `facts.related` (viewer, read-only, experimental). + # Required: org, namespace, entity. + def related(body = nil, request_options: nil, **fields) + call_op("facts.related", body, fields, request_options) + end + + # `facts.traverse` (viewer, read-only). + # Walk the entity co-occurrence graph N hops out from a seed, one + # Required: org, namespace, seed_entity. + def traverse(body = nil, request_options: nil, **fields) + call_op("facts.traverse", body, fields, request_options) + end + end + + # The `grants.*` operations. + class GrantsOps < OpGroup + # `grants.approve` (admin, writes, Idempotency-Key, experimental). + # Approve (or reject) a pending grant request. + # Required: org, namespace, subject. + def approve(body = nil, request_options: nil, **fields) + call_op("grants.approve", body, fields, request_options) + end + + # `grants.create` (admin, writes, Idempotency-Key). + # Required: org, namespace, subject, role. + def create(body = nil, request_options: nil, **fields) + call_op("grants.create", body, fields, request_options) + end + + # `grants.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("grants.list", body, fields, request_options) + end + + # `grants.pending_for_me` (viewer, read-only, experimental). + # Required: org. + def pending_for_me(body = nil, request_options: nil, **fields) + call_op("grants.pending_for_me", body, fields, request_options) + end + + # `grants.revoke` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, subject. + def revoke(body = nil, request_options: nil, **fields) + call_op("grants.revoke", body, fields, request_options) + end + + # `grants.share_agent` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, grantee. + def share_agent(body = nil, request_options: nil, **fields) + call_op("grants.share_agent", body, fields, request_options) + end + + # `grants.unshare_agent` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, grantee. + def unshare_agent(body = nil, request_options: nil, **fields) + call_op("grants.unshare_agent", body, fields, request_options) + end + end + + # The `help.*` operations. + class HelpOps < OpGroup + # `help.get` (viewer, read-only, experimental). + # Read one page of this build's documentation, or one section of it. + # Required: path. + def get(body = nil, request_options: nil, **fields) + call_op("help.get", body, fields, request_options) + end + + # `help.search` (viewer, read-only, experimental). + # Search this build's documentation. + # Required: query. + def search(body = nil, request_options: nil, **fields) + call_op("help.search", body, fields, request_options) + end + end + + # The `inbox.*` operations. + class InboxOps < OpGroup + # `inbox.list` (viewer, read-only, experimental). + # Inboxes the caller may see: those owned by ``namespace`` (the + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("inbox.list", body, fields, request_options) + end + + # `inbox.policy_list` (viewer, read-only, experimental). + # Required: org, namespace, inbox. + def policy_list(body = nil, request_options: nil, **fields) + call_op("inbox.policy_list", body, fields, request_options) + end + + # `inbox.policy_set` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, inbox, poster, mode. + def policy_set(body = nil, request_options: nil, **fields) + call_op("inbox.policy_set", body, fields, request_options) + end + + # `inbox.principals` (admin, writes, Idempotency-Key, experimental). + # The identities loom already knows in the org — the poster picker's + # Required: org, namespace, inbox. + def principals(body = nil, request_options: nil, **fields) + call_op("inbox.principals", body, fields, request_options) + end + + # `inbox.register` (admin, writes, Idempotency-Key, experimental). + # ``namespace`` is the owner namespace (the caller must be its admin). + # Required: org, namespace, inbox, owner_agent. + def register(body = nil, request_options: nil, **fields) + call_op("inbox.register", body, fields, request_options) + end + end + + # The `insights.*` operations. + class InsightsOps < OpGroup + # `insights.catalog` (viewer, read-only, experimental). + # Required: org, namespace. + def catalog(body = nil, request_options: nil, **fields) + call_op("insights.catalog", body, fields, request_options) + end + + # `insights.query` (viewer, read-only, experimental). + # Required: org, namespace, sql. + def query(body = nil, request_options: nil, **fields) + call_op("insights.query", body, fields, request_options) + end + end + + # The `knowledge.*` operations. + class KnowledgeOps < OpGroup + # `knowledge.add` (writer, writes, Idempotency-Key). + # Required: org, namespace, source_uri, content. + def add(body = nil, request_options: nil, **fields) + call_op("knowledge.add", body, fields, request_options) + end + + # `knowledge.bulk_add` (writer, writes, Idempotency-Key). + # Batched ingestion: many documents in one CH round-trip. + # Required: org, namespace, entries. + def bulk_add(body = nil, request_options: nil, **fields) + call_op("knowledge.bulk_add", body, fields, request_options) + end + + # `knowledge.bulk_delete` (writer, writes, Idempotency-Key, experimental). + # Soft-delete multiple documents by source_uri, in one commit. + # Required: org, namespace, source_uris. + def bulk_delete(body = nil, request_options: nil, **fields) + call_op("knowledge.bulk_delete", body, fields, request_options) + end + + # `knowledge.dataset_approve` (writer, writes, experimental). + # Approve a dataset's schema, retyping the columns named: its rows are + # Required: org, namespace, source_uri, dataset_id, snapshot_id. + def dataset_approve(body = nil, request_options: nil, **fields) + call_op("knowledge.dataset_approve", body, fields, request_options) + end + + # `knowledge.dataset_get` (viewer, read-only, experimental). + # The typed datasets an ingested file's tables became: their schemas, + # Required: org, namespace, source_uri. + def dataset_get(body = nil, request_options: nil, **fields) + call_op("knowledge.dataset_get", body, fields, request_options) + end + + # `knowledge.dedup_list` (admin, writes, Idempotency-Key, experimental). + # List cross-URI doc duplicates and (optionally) chunk-overlap + # Required: org, namespace. + def dedup_list(body = nil, request_options: nil, **fields) + call_op("knowledge.dedup_list", body, fields, request_options) + end + + # `knowledge.dedup_resolve` (admin, writes, Idempotency-Key, experimental). + # Resolve one document duplicate pair. + # Required: org, namespace, canonical_uri, duplicate_uri, decision, confirm_duplicate_uri. + def dedup_resolve(body = nil, request_options: nil, **fields) + call_op("knowledge.dedup_resolve", body, fields, request_options) + end + + # `knowledge.delete` (writer, writes, Idempotency-Key, experimental). + # Soft-delete a document by source_uri: writes its tombstone. + # Required: org, namespace, source_uri. + def delete(body = nil, request_options: nil, **fields) + call_op("knowledge.delete", body, fields, request_options) + end + + # `knowledge.formats` (viewer, read-only, experimental). + # The document formats this deployment reads, as `knowledge.ingest` sends + # Required: org, namespace. + def formats(body = nil, request_options: nil, **fields) + call_op("knowledge.formats", body, fields, request_options) + end + + # `knowledge.gaps.draft` (admin, writes, Idempotency-Key, experimental). + # Draft a definition from a knowledge gap for an admin to review. + # Required: org, namespace, gap_id. + def gaps_draft(body = nil, request_options: nil, **fields) + call_op("knowledge.gaps.draft", body, fields, request_options) + end + + # `knowledge.gaps.list` (admin, writes, Idempotency-Key, experimental). + # The questions people keep asking in a namespace that nothing answers. + # Required: org, namespace. + def gaps_list(body = nil, request_options: nil, **fields) + call_op("knowledge.gaps.list", body, fields, request_options) + end + + # `knowledge.get` (viewer, read-only). + # Fetch a single document by source_uri. + # Required: org, namespace, source_uri. + def get(body = nil, request_options: nil, **fields) + call_op("knowledge.get", body, fields, request_options) + end + + # `knowledge.ingest` (writer, writes, experimental). + # Extract an uploaded file (the extractor service parses it, the server + # Required: org, namespace, upload_id, source_uri. + def ingest(body = nil, request_options: nil, **fields) + call_op("knowledge.ingest", body, fields, request_options) + end + + # `knowledge.ingest_cancel` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, ingestion_id. + def ingest_cancel(body = nil, request_options: nil, **fields) + call_op("knowledge.ingest_cancel", body, fields, request_options) + end + + # `knowledge.ingest_status` (viewer, read-only, experimental). + # A knowledge.ingest job's state, stage, coverage, failure and published + # Required: org, namespace, ingestion_id. + def ingest_status(body = nil, request_options: nil, **fields) + call_op("knowledge.ingest_status", body, fields, request_options) + end + + # `knowledge.inspect` (viewer, read-only, experimental). + # Report a namespace's documents, read-only. + # Required: org, namespace. + def inspect_(body = nil, request_options: nil, **fields) + call_op("knowledge.inspect", body, fields, request_options) + end + + # `knowledge.list` (viewer, read-only). + # Paginated listing of the documents of one namespace or several, for curation tools. + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("knowledge.list", body, fields, request_options) + end + + # `knowledge.move` (writer, writes, Idempotency-Key, experimental). + # Move documents to another namespace of the org: a collection, `@me` (an end user's + # Required: org, namespace, to_namespace, source_uris. + def move(body = nil, request_options: nil, **fields) + call_op("knowledge.move", body, fields, request_options) + end + + # `knowledge.outline` (viewer, read-only, experimental). + # A document's table of contents, as recorded on its chunks at ingest, + # Required: org, namespace, source_uri. + def outline(body = nil, request_options: nil, **fields) + call_op("knowledge.outline", body, fields, request_options) + end + + # `knowledge.query` (viewer, read-only, experimental). + # Calculate over the live snapshots of ingested datasets with a typed + # Required: org, namespace, datasets. + def query(body = nil, request_options: nil, **fields) + call_op("knowledge.query", body, fields, request_options) + end + + # `knowledge.query_history.add` (admin, writes, experimental). + # Register a read-only ClickHouse query-history source for definition drafts. + # Required: org, namespace, name, host, user, password, databases. + def query_history_add(body = nil, request_options: nil, **fields) + call_op("knowledge.query_history.add", body, fields, request_options) + end + + # `knowledge.query_history.list` (admin, writes, Idempotency-Key, experimental). + # List the namespace's registered query-history sources. + # Required: org, namespace. + def query_history_list(body = nil, request_options: nil, **fields) + call_op("knowledge.query_history.list", body, fields, request_options) + end + + # `knowledge.query_history.remove` (admin, writes, Idempotency-Key, experimental). + # Remove a query-history source registration from the namespace. + # Required: org, namespace, name. + def query_history_remove(body = nil, request_options: nil, **fields) + call_op("knowledge.query_history.remove", body, fields, request_options) + end + + # `knowledge.reads` (viewer, read-only, experimental). + # How often agents opened each document over the last `days` (`knowledge.get` + # Required: org, namespace. + def reads(body = nil, request_options: nil, **fields) + call_op("knowledge.reads", body, fields, request_options) + end + + # `knowledge.restore` (writer, writes, Idempotency-Key, experimental). + # Undo a `knowledge.delete` or `knowledge.bulk_delete` of one document. + # Required: org, namespace, source_uri. + def restore(body = nil, request_options: nil, **fields) + call_op("knowledge.restore", body, fields, request_options) + end + + # `knowledge.search` (viewer, read-only). + # Required: org, namespace, query. + def search(body = nil, request_options: nil, **fields) + call_op("knowledge.search", body, fields, request_options) + end + + # `knowledge.source.add` (writer, writes, experimental). + # Register a document source on a namespace: a kind, what it reads (items + # Required: org, namespace, name, kind. + def source_add(body = nil, request_options: nil, **fields) + call_op("knowledge.source.add", body, fields, request_options) + end + + # `knowledge.source.check` (writer, writes, Idempotency-Key, experimental). + # Probe a registered document source with its stored credential now (a check of + # Required: org, namespace, name. + def source_check(body = nil, request_options: nil, **fields) + call_op("knowledge.source.check", body, fields, request_options) + end + + # `knowledge.source.inspect` (viewer, read-only, experimental). + # One registered document source: its items, its sync state and the + # Required: org, namespace, name. + def source_inspect(body = nil, request_options: nil, **fields) + call_op("knowledge.source.inspect", body, fields, request_options) + end + + # `knowledge.source.list` (viewer, read-only, experimental). + # The document sources registered on a namespace, with each one's sync + # Required: org, namespace. + def source_list(body = nil, request_options: nil, **fields) + call_op("knowledge.source.list", body, fields, request_options) + end + + # `knowledge.source.parse_links` (viewer, read-only, experimental). + # Read pasted links as a source's items, with no request to any store and + # Required: org, namespace, links. + def source_parse_links(body = nil, request_options: nil, **fields) + call_op("knowledge.source.parse_links", body, fields, request_options) + end + + # `knowledge.source.push_configure` (admin, writes, experimental). + # Enable provider sync hints for an existing source, or disable its setup. + # Required: org, namespace, name. + def source_push_configure(body = nil, request_options: nil, **fields) + call_op("knowledge.source.push_configure", body, fields, request_options) + end + + # `knowledge.source.push_confirm` (admin, writes, experimental). + # Activate the exact pending setup. + # Required: org, namespace, name, generation. + def source_push_confirm(body = nil, request_options: nil, **fields) + call_op("knowledge.source.push_confirm", body, fields, request_options) + end + + # `knowledge.source.push_status` (admin, writes, experimental). + # Read push setup as a namespace admin. + # Required: org, namespace, name. + def source_push_status(body = nil, request_options: nil, **fields) + call_op("knowledge.source.push_status", body, fields, request_options) + end + + # `knowledge.source.remove` (writer, writes, experimental). + # Retire a registered document source: its registry row goes inactive and its + # Required: org, namespace, name, confirm. + def source_remove(body = nil, request_options: nil, **fields) + call_op("knowledge.source.remove", body, fields, request_options) + end + + # `knowledge.source.rotate` (admin, writes, experimental). + # Replace a registered document source's credential. A namespace admin may; + # Required: org, namespace, name, credential. + def source_rotate(body = nil, request_options: nil, **fields) + call_op("knowledge.source.rotate", body, fields, request_options) + end + + # `knowledge.source.sync_now` (writer, writes, Idempotency-Key, experimental). + # Record a request to sync one document source in its sync state: the sync + # Required: org, namespace, name. + def source_sync_now(body = nil, request_options: nil, **fields) + call_op("knowledge.source.sync_now", body, fields, request_options) + end + + # `knowledge.source.update` (writer, writes, experimental). + # Add items to a registered document source or remove them, or change a gdrive + # Required: org, namespace, name. + def source_update(body = nil, request_options: nil, **fields) + call_op("knowledge.source.update", body, fields, request_options) + end + + # `knowledge.synthesize` (viewer, writes, Idempotency-Key, experimental). + # Complete a task over WHOLE documents, not a search slice: + # Required: org, namespace, task. + def synthesize(body = nil, request_options: nil, **fields) + call_op("knowledge.synthesize", body, fields, request_options) + end + + # `knowledge.update_metadata` (writer, writes, Idempotency-Key, experimental). + # Edit doc-level metadata (title, description, tags). Leaves chunk + # Required: org, namespace, source_uri. + def update_metadata(body = nil, request_options: nil, **fields) + call_op("knowledge.update_metadata", body, fields, request_options) + end + + # `knowledge.upsert` (writer, writes, Idempotency-Key, experimental). + # Same fields as knowledge.add. Behavior: replaces existing chunks for + # Required: org, namespace, source_uri, content. + def upsert(body = nil, request_options: nil, **fields) + call_op("knowledge.upsert", body, fields, request_options) + end + end + + # The `learnings.*` operations. + class LearningsOps < OpGroup + # `learnings.list` (viewer, read-only, experimental). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("learnings.list", body, fields, request_options) + end + + # `learnings.quality` (viewer, read-only, experimental). + # Required: org. + def quality(body = nil, request_options: nil, **fields) + call_op("learnings.quality", body, fields, request_options) + end + + # `learnings.review` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, candidate_id, decision. + def review(body = nil, request_options: nil, **fields) + call_op("learnings.review", body, fields, request_options) + end + end + + # The `memory.*` operations. + class MemoryOps < OpGroup + # `memory.agents_list` (viewer, read-only). + # Distinct agent names that have ever written into (org, namespace). + # Required: org, namespace. + def agents_list(body = nil, request_options: nil, **fields) + call_op("memory.agents_list", body, fields, request_options) + end + + # `memory.aggregate` (viewer, read-only, experimental). + # Templated SQL aggregation over typed records in loom.memory. + # Required: org, namespace, agent. + def aggregate(body = nil, request_options: nil, **fields) + call_op("memory.aggregate", body, fields, request_options) + end + + # `memory.append_batch` (writer, writes, Idempotency-Key, experimental). + # Append distinct episodic occurrences atomically on the Postgres authority. + # Required: org, namespace, agent, entries. + def append_batch(body = nil, request_options: nil, **fields) + call_op("memory.append_batch", body, fields, request_options) + end + + # `memory.apply` (writer, writes, experimental). + # One scope grammar for every write that can touch more than one row. + # Required: org, namespace, agent, target, action, reason. + def apply(body = nil, request_options: nil, **fields) + call_op("memory.apply", body, fields, request_options) + end + + # `memory.ask` (viewer, read-only). + # Ask a question and get a grounded answer synthesized from the caller's + # Required: org, namespace, query. + def ask(body = nil, request_options: nil, **fields) + call_op("memory.ask", body, fields, request_options) + end + + # `memory.assign_category` (writer, writes, Idempotency-Key, experimental). + # Link a memory to one of the namespace's registered categories. + # Required: org, namespace, memory_key, category_name. + def assign_category(body = nil, request_options: nil, **fields) + call_op("memory.assign_category", body, fields, request_options) + end + + # `memory.auto_retirements` (viewer, read-only, experimental). + # The memories Loom retired on its own (the conflict resolver, `newest_wins`), + # Required: org, namespace. + def auto_retirements(body = nil, request_options: nil, **fields) + call_op("memory.auto_retirements", body, fields, request_options) + end + + # `memory.backlinks` (viewer, read-only, experimental). + # What points at one memory: its version chain, the + # Required: org, namespace, agent, memory_key. + def backlinks(body = nil, request_options: nil, **fields) + call_op("memory.backlinks", body, fields, request_options) + end + + # `memory.brief` (viewer, read-only). + # A task or question to orient on. Same identity as every memory op. + # Required: org, namespace, agent, query. + def brief(body = nil, request_options: nil, **fields) + call_op("memory.brief", body, fields, request_options) + end + + # `memory.bulk_get` (viewer, read-only). + # Fetch many memory entries by key in one CH round-trip. + # Required: org, namespace, agent, memory_keys. + def bulk_get(body = nil, request_options: nil, **fields) + call_op("memory.bulk_get", body, fields, request_options) + end + + # `memory.bulk_set` (writer, writes, Idempotency-Key). + # Insert many memory entries in one batched CH insert. + # Required: org, namespace, agent, entries. + def bulk_set(body = nil, request_options: nil, **fields) + call_op("memory.bulk_set", body, fields, request_options) + end + + # `memory.clear` (admin, writes, Idempotency-Key). + # Bulk-tombstone memories in one scope. + # Required: org, namespace, confirm_subject. + def clear(body = nil, request_options: nil, **fields) + call_op("memory.clear", body, fields, request_options) + end + + # `memory.consolidate` (writer, writes). + # Periodic consolidation pass — merges fragmented memories about the same + # Required: org, namespace, agent. + def consolidate(body = nil, request_options: nil, **fields) + call_op("memory.consolidate", body, fields, request_options) + end + + # `memory.copy_to` (writer, writes, experimental). + # Self-service copy of a memory into another namespace. + # Required: from_org, from_namespace, memory_key, to_namespace. + def copy_to(body = nil, request_options: nil, **fields) + call_op("memory.copy_to", body, fields, request_options) + end + + # `memory.cross_promote` (viewer, writes, experimental). + # Cross-namespace promotion with provenance. + # Required: from_org, from_namespace, from_memory_id, to_namespace. + def cross_promote(body = nil, request_options: nil, **fields) + call_op("memory.cross_promote", body, fields, request_options) + end + + # `memory.dedup_collapse` (writer, writes, Idempotency-Key, experimental). + # Collapse every duplicate pair of a namespace onto its canonical — no + # Required: org, namespace. + def dedup_collapse(body = nil, request_options: nil, **fields) + call_op("memory.dedup_collapse", body, fields, request_options) + end + + # `memory.dedup_list` (admin, writes, Idempotency-Key). + # List clusters of status='duplicate' rows in a namespace. + # Required: org, namespace. + def dedup_list(body = nil, request_options: nil, **fields) + call_op("memory.dedup_list", body, fields, request_options) + end + + # `memory.dedup_resolve` (admin, writes, Idempotency-Key). + # Resolve one duplicate pair. + # Required: org, namespace, canonical_id, duplicate_id, decision, confirm_canonical_key. + def dedup_resolve(body = nil, request_options: nil, **fields) + call_op("memory.dedup_resolve", body, fields, request_options) + end + + # `memory.definitions.list` (admin, writes, Idempotency-Key, experimental). + # The namespace's shared definitions and whether each is governed. + # Required: org, namespace. + def definitions_list(body = nil, request_options: nil, **fields) + call_op("memory.definitions.list", body, fields, request_options) + end + + # `memory.delete` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent, memory_key. + def delete(body = nil, request_options: nil, **fields) + call_op("memory.delete", body, fields, request_options) + end + + # `memory.delete_version` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, memory_key, version. + def delete_version(body = nil, request_options: nil, **fields) + call_op("memory.delete_version", body, fields, request_options) + end + + # `memory.demonstrate` (viewer, read-only, experimental). + # Required: org, namespace, query. + def demonstrate(body = nil, request_options: nil, **fields) + call_op("memory.demonstrate", body, fields, request_options) + end + + # `memory.demote` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, memory_key. + def demote(body = nil, request_options: nil, **fields) + call_op("memory.demote", body, fields, request_options) + end + + # `memory.digests` (viewer, read-only). + # List the session digests of a namespace. `session_id` + # Required: org, namespace, agent. + def digests(body = nil, request_options: nil, **fields) + call_op("memory.digests", body, fields, request_options) + end + + # `memory.evidence` (viewer, read-only). + # List the source turns a memory was extracted from, with the supporting + # Required: org, namespace, agent, memory_key. + def evidence(body = nil, request_options: nil, **fields) + call_op("memory.evidence", body, fields, request_options) + end + + # `memory.export_evidence` (viewer, read-only). + # Required: org, namespace. + def export_evidence(body = nil, request_options: nil, **fields) + call_op("memory.export_evidence", body, fields, request_options) + end + + # `memory.exposure_summary` (admin, writes, Idempotency-Key, experimental). + # Per-(actor, agent) distinct memory keys returned by reads of a + # Required: org, namespace. + def exposure_summary(body = nil, request_options: nil, **fields) + call_op("memory.exposure_summary", body, fields, request_options) + end + + # `memory.extraction_retry_mine` (writer, writes, Idempotency-Key, experimental). + # Replay your failed deferred memory.set_from_messages batches once more, by queue_id. + # Required: org, namespace, queue_ids. + def extraction_retry_mine(body = nil, request_options: nil, **fields) + call_op("memory.extraction_retry_mine", body, fields, request_options) + end + + # `memory.extraction_status` (viewer, read-only). + # State of deferred set_from_messages batches. + # Required: org, namespace. + def extraction_status(body = nil, request_options: nil, **fields) + call_op("memory.extraction_status", body, fields, request_options) + end + + # `memory.extraction_status_mine` (viewer, read-only, experimental). + # Your deferred memory.set_from_messages batches, by the queue_id each call returned. + # Required: org, namespace, queue_ids. + def extraction_status_mine(body = nil, request_options: nil, **fields) + call_op("memory.extraction_status_mine", body, fields, request_options) + end + + # `memory.for_file` (viewer, read-only). + # Required: org, namespace, path. + def for_file(body = nil, request_options: nil, **fields) + call_op("memory.for_file", body, fields, request_options) + end + + # `memory.get` (viewer, read-only). + # Required: org, namespace, agent, memory_key. + def get(body = nil, request_options: nil, **fields) + call_op("memory.get", body, fields, request_options) + end + + # `memory.get_by_id` (viewer, read-only). + # Required: org, memory_id. + def get_by_id(body = nil, request_options: nil, **fields) + call_op("memory.get_by_id", body, fields, request_options) + end + + # `memory.health` (viewer, read-only). + # Knowledge-base health for (org, namespace): how much of what is stored + # Required: org, namespace. + def health(body = nil, request_options: nil, **fields) + call_op("memory.health", body, fields, request_options) + end + + # `memory.history` (viewer, read-only, experimental). + # Enumerate the version history of one memory_key. Returns rows + # Required: org, namespace, agent, memory_key. + def history(body = nil, request_options: nil, **fields) + call_op("memory.history", body, fields, request_options) + end + + # `memory.import` (writer, writes, Idempotency-Key, experimental). + # Import items another memory system distilled, through every check a write makes. + # Required: org, namespace, agent, entries. + def import(body = nil, request_options: nil, **fields) + call_op("memory.import", body, fields, request_options) + end + + # `memory.import_curated` (writer, writes, experimental). + # Required: org, namespace, content. + def import_curated(body = nil, request_options: nil, **fields) + call_op("memory.import_curated", body, fields, request_options) + end + + # `memory.import_evidence` (writer, writes). + # Required: org, namespace, agent. + def import_evidence(body = nil, request_options: nil, **fields) + call_op("memory.import_evidence", body, fields, request_options) + end + + # `memory.inspect` (viewer, read-only, experimental). + # Inspect one user, agent or session of a namespace, read-only. + # Required: org, namespace, subject, id. + def inspect_(body = nil, request_options: nil, **fields) + call_op("memory.inspect", body, fields, request_options) + end + + # `memory.keys` (viewer, read-only, experimental). + # Required: org, namespace. + def keys(body = nil, request_options: nil, **fields) + call_op("memory.keys", body, fields, request_options) + end + + # `memory.lineage` (viewer, read-only, experimental). + # Assemble the provenance chain for a SHARED memory. + # Required: org, namespace, agent, memory_key. + def lineage(body = nil, request_options: nil, **fields) + call_op("memory.lineage", body, fields, request_options) + end + + # `memory.link` (writer, writes). + # Author an explicit edge between two memories (or two entities). + # Required: org, namespace, from_key, to_key. + def link(body = nil, request_options: nil, **fields) + call_op("memory.link", body, fields, request_options) + end + + # `memory.list` (viewer, read-only). + # List memory keys under this identity, optionally filtered. + # Required: org, namespace, agent. + def list(body = nil, request_options: nil, **fields) + call_op("memory.list", body, fields, request_options) + end + + # `memory.lock` (writer, writes, experimental). + # Lock one row, refusing a changed source with retryable 503 + # Required: org, namespace, agent, memory_key, reason. + def lock(body = nil, request_options: nil, **fields) + call_op("memory.lock", body, fields, request_options) + end + + # `memory.move` (writer, writes). + # Rename `from_key` to `to_key`, leaving the old key answering. + # Required: org, namespace, agent, from_key, to_key. + def move(body = nil, request_options: nil, **fields) + call_op("memory.move", body, fields, request_options) + end + + # `memory.outcome` (writer, writes, experimental). + # External outcome signal for a memory row. + # Required: org, namespace, outcome. + def outcome(body = nil, request_options: nil, **fields) + call_op("memory.outcome", body, fields, request_options) + end + + # `memory.outcome_run` (writer, writes). + # Apply one outcome to many recalled memories in a single call — the bulk + # Required: org, namespace, outcome. + def outcome_run(body = nil, request_options: nil, **fields) + call_op("memory.outcome_run", body, fields, request_options) + end + + # `memory.outline` (viewer, read-only, experimental). + # A namespace's table of contents, read from structure alone: row counts by type, + # Required: org, namespace, agent. + def outline(body = nil, request_options: nil, **fields) + call_op("memory.outline", body, fields, request_options) + end + + # `memory.owner_report` (viewer, read-only, experimental). + # The owner's view of their memory: what they own, who + # Required: org. + def owner_report(body = nil, request_options: nil, **fields) + call_op("memory.owner_report", body, fields, request_options) + end + + # `memory.pin` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, memory_key, value. + def pin(body = nil, request_options: nil, **fields) + call_op("memory.pin", body, fields, request_options) + end + + # `memory.promote` (admin, writes, experimental). + # Promote a single source memory to the namespace's shared layer. + # Required: org, namespace, agent, memory_key. + def promote(body = nil, request_options: nil, **fields) + call_op("memory.promote", body, fields, request_options) + end + + # `memory.proposal_decide` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, memory_keys, decision. + def proposal_decide(body = nil, request_options: nil, **fields) + call_op("memory.proposal_decide", body, fields, request_options) + end + + # `memory.proposals` (viewer, read-only, experimental). + # Required: org, namespace. + def proposals(body = nil, request_options: nil, **fields) + call_op("memory.proposals", body, fields, request_options) + end + + # `memory.provenance` (viewer, read-only). + # Resolve a memory's origin for user-facing provenance. + # Required: org, namespace, agent, memory_key. + def provenance(body = nil, request_options: nil, **fields) + call_op("memory.provenance", body, fields, request_options) + end + + # `memory.recall` (viewer, read-only). + # Search the raw conversation turns behind this namespace's memories — + # Required: org, namespace, agent. + def recall(body = nil, request_options: nil, **fields) + call_op("memory.recall", body, fields, request_options) + end + + # `memory.record.conflicts` (viewer, read-only, experimental). + # Field-level disagreements recorded when a typed record superseded the + # Required: org, namespace. + def record_conflicts(body = nil, request_options: nil, **fields) + call_op("memory.record.conflicts", body, fields, request_options) + end + + # `memory.record.history` (viewer, read-only). + # Required: org, namespace, record_id. + def record_history(body = nil, request_options: nil, **fields) + call_op("memory.record.history", body, fields, request_options) + end + + # `memory.record.query` (viewer, read-only). + # Required: org, namespace, schema_name. + def record_query(body = nil, request_options: nil, **fields) + call_op("memory.record.query", body, fields, request_options) + end + + # `memory.record.write` (writer, writes). + # Required: org, namespace, schema_name, fields. + def record_write(body = nil, request_options: nil, **fields) + call_op("memory.record.write", body, fields, request_options) + end + + # `memory.redact` (admin, writes, Idempotency-Key, experimental). + # Scrub the value of a historical memory row, preserving its audit entry. + # Required: org, memory_id, version. + def redact(body = nil, request_options: nil, **fields) + call_op("memory.redact", body, fields, request_options) + end + + # `memory.reindex` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def reindex(body = nil, request_options: nil, **fields) + call_op("memory.reindex", body, fields, request_options) + end + + # `memory.reject` (writer, writes, Idempotency-Key, experimental). + # Mark a memory as explicitly rejected (extractor / user review decided the + # Required: org, namespace, agent, memory_key. + def reject(body = nil, request_options: nil, **fields) + call_op("memory.reject", body, fields, request_options) + end + + # `memory.related` (viewer, read-only, experimental). + # Find memories sharing entities with the source memory. + # Required: org, namespace, agent, memory_key. + def related(body = nil, request_options: nil, **fields) + call_op("memory.related", body, fields, request_options) + end + + # `memory.resolve_orphan_duplicates` (writer, writes, Idempotency-Key). + # Scan (org, namespace) for orphaned duplicate rows and re-activate them. + # Required: org, namespace. + def resolve_orphan_duplicates(body = nil, request_options: nil, **fields) + call_op("memory.resolve_orphan_duplicates", body, fields, request_options) + end + + # `memory.restore` (writer, writes, Idempotency-Key). + # Reverse automatic retirement when no deletion or erasure refusal blocks the value. + # Required: org, namespace, agent, memory_key. + def restore(body = nil, request_options: nil, **fields) + call_op("memory.restore", body, fields, request_options) + end + + # `memory.search` (viewer, read-only). + # Semantic search over the agent's own memory. + # Required: org, namespace, query. + def search(body = nil, request_options: nil, **fields) + call_op("memory.search", body, fields, request_options) + end + + # `memory.search_trace` (viewer, read-only). + # Same shape as memory.search; returns the vector leg's per-candidate scoring + # Required: org, namespace, query. + def search_trace(body = nil, request_options: nil, **fields) + call_op("memory.search_trace", body, fields, request_options) + end + + # `memory.search_trace_log` (viewer, read-only). + # Read loom.search_trace_log for a namespace (requires the telemetry + # Required: org, namespace. + def search_trace_log(body = nil, request_options: nil, **fields) + call_op("memory.search_trace_log", body, fields, request_options) + end + + # `memory.set` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent, memory_key, value. + def set(body = nil, request_options: nil, **fields) + call_op("memory.set", body, fields, request_options) + end + + # `memory.set_from_messages` (writer, writes). + # Run LLM extraction on `messages` and write the extracted facts. + # Required: org, namespace, agent, messages. + def set_from_messages(body = nil, request_options: nil, **fields) + call_op("memory.set_from_messages", body, fields, request_options) + end + + # `memory.stack` (viewer, read-only, experimental). + # Compose a token-budgeted recall bundle for agent wake-up. + # Required: org, namespace, agent. + def stack(body = nil, request_options: nil, **fields) + call_op("memory.stack", body, fields, request_options) + end + + # `memory.statuses` (viewer, read-only, experimental). + # The current status of some memories, by id: which automatic retirements still + # Required: org, namespace, memory_ids. + def statuses(body = nil, request_options: nil, **fields) + call_op("memory.statuses", body, fields, request_options) + end + + # `memory.sweep_expired` (admin, writes, Idempotency-Key, experimental). + # Run one expiry-sweep pass now — the same pass the + # Required: org, namespace. + def sweep_expired(body = nil, request_options: nil, **fields) + call_op("memory.sweep_expired", body, fields, request_options) + end + + # `memory.timeline` (viewer, read-only, experimental). + # Return memories about an entity (or matching a tag filter) in strict + # Required: org, namespace, agent. + def timeline(body = nil, request_options: nil, **fields) + call_op("memory.timeline", body, fields, request_options) + end + + # `memory.touch` (writer, writes, experimental). + # Change only a memory's expiry: set a new TTL (`ttl_seconds`) or clear + # Required: org, namespace, agent. + def touch(body = nil, request_options: nil, **fields) + call_op("memory.touch", body, fields, request_options) + end + + # `memory.unlock` (admin, writes, Idempotency-Key, experimental). + # Unlock one row, refusing a changed source with retryable 503 + # Required: org, namespace, agent, memory_key. + def unlock(body = nil, request_options: nil, **fields) + call_op("memory.unlock", body, fields, request_options) + end + + # `memory.unpin` (admin, writes, Idempotency-Key, experimental). + # Remove the write-time pin from one live memory. + # Required: org, namespace, agent, memory_key. + def unpin(body = nil, request_options: nil, **fields) + call_op("memory.unpin", body, fields, request_options) + end + + # `memory.update` (writer, writes). + # Key-addressed update: the fact changed or got more specific. + # Required: org, namespace, memory_key. + def update(body = nil, request_options: nil, **fields) + call_op("memory.update", body, fields, request_options) + end + + # `memory.update_by_id` (writer, writes, Idempotency-Key). + # Required: org, memory_id. + def update_by_id(body = nil, request_options: nil, **fields) + call_op("memory.update_by_id", body, fields, request_options) + end + + # `memory.verify` (writer, writes, Idempotency-Key). + # Attest or revoke, refusing a changed source with retryable 503 + # Required: org. + def verify(body = nil, request_options: nil, **fields) + call_op("memory.verify", body, fields, request_options) + end + end + + # The `memory_schema.*` operations. + class MemorySchemaOps < OpGroup + # `memory_schema.approve` (admin, writes, experimental). + # Required: org, namespace, name, decision. + def approve(body = nil, request_options: nil, **fields) + call_op("memory_schema.approve", body, fields, request_options) + end + + # `memory_schema.list` (viewer, read-only, experimental). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("memory_schema.list", body, fields, request_options) + end + + # `memory_schema.propose` (writer, writes, experimental). + # Required: org, namespace, name, fields. + def propose(body = nil, request_options: nil, **fields) + call_op("memory_schema.propose", body, fields, request_options) + end + + # `memory_schema.register` (admin, writes). + # Required: org, namespace, name, fields. + def register(body = nil, request_options: nil, **fields) + call_op("memory_schema.register", body, fields, request_options) + end + end + + # The `mentor.*` operations. + class MentorOps < OpGroup + # `mentor.brief` (viewer, read-only). + # One agent's usage profile and the store's hints. `agent` defaults + # Required: org, namespace. + def brief(body = nil, request_options: nil, **fields) + call_op("mentor.brief", body, fields, request_options) + end + + # `mentor.guide` (viewer, read-only, experimental). + # The agent guide this server ships; the same for every caller. + def guide(body = nil, request_options: nil, **fields) + call_op("mentor.guide", body, fields, request_options) + end + end + + # The `namespace.*` operations. + class NamespaceOps < OpGroup + # `namespace.audit` (viewer, read-only). + # Usage report for one namespace: is it being used as a memory, or as an + # Required: org, namespace. + def audit(body = nil, request_options: nil, **fields) + call_op("namespace.audit", body, fields, request_options) + end + + # `namespace.browse` (viewer, read-only). + # Required: org. + def browse(body = nil, request_options: nil, **fields) + call_op("namespace.browse", body, fields, request_options) + end + + # `namespace.cancel_request` (viewer, writes, Idempotency-Key, experimental). + # Withdraw the caller's own pending elevation request. + # Required: org, namespace. + def cancel_request(body = nil, request_options: nil, **fields) + call_op("namespace.cancel_request", body, fields, request_options) + end + + # `namespace.delete` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def delete(body = nil, request_options: nil, **fields) + call_op("namespace.delete", body, fields, request_options) + end + + # `namespace.get` (viewer, read-only). + # Required: org, namespace. + def get(body = nil, request_options: nil, **fields) + call_op("namespace.get", body, fields, request_options) + end + + # `namespace.guide_get` (viewer, read-only, experimental). + # Required: org, namespace. + def guide_get(body = nil, request_options: nil, **fields) + call_op("namespace.guide_get", body, fields, request_options) + end + + # `namespace.guide_history` (viewer, read-only, experimental). + # Required: org, namespace. + def guide_history(body = nil, request_options: nil, **fields) + call_op("namespace.guide_history", body, fields, request_options) + end + + # `namespace.guide_set` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, content, expected_revision. + def guide_set(body = nil, request_options: nil, **fields) + call_op("namespace.guide_set", body, fields, request_options) + end + + # `namespace.inventory` (viewer, read-only, experimental). + # What one namespace holds and who appears in it, with what was not counted. + # Required: org, namespace. + def inventory(body = nil, request_options: nil, **fields) + call_op("namespace.inventory", body, fields, request_options) + end + + # `namespace.join` (viewer, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def join(body = nil, request_options: nil, **fields) + call_op("namespace.join", body, fields, request_options) + end + + # `namespace.leave` (viewer, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def leave(body = nil, request_options: nil, **fields) + call_op("namespace.leave", body, fields, request_options) + end + + # `namespace.list` (org_admin, writes, Idempotency-Key, experimental). + # Required: org. + def list(body = nil, request_options: nil, **fields) + call_op("namespace.list", body, fields, request_options) + end + + # `namespace.list_categories` (viewer, read-only, experimental). + # Required: org, namespace. + def list_categories(body = nil, request_options: nil, **fields) + call_op("namespace.list_categories", body, fields, request_options) + end + + # `namespace.list_mine` (viewer, read-only). + # Required: org. + def list_mine(body = nil, request_options: nil, **fields) + call_op("namespace.list_mine", body, fields, request_options) + end + + # `namespace.list_ontology` (viewer, read-only, experimental). + # Required: org, namespace. + def list_ontology(body = nil, request_options: nil, **fields) + call_op("namespace.list_ontology", body, fields, request_options) + end + + # `namespace.mark_seen` (viewer, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def mark_seen(body = nil, request_options: nil, **fields) + call_op("namespace.mark_seen", body, fields, request_options) + end + + # `namespace.register` (viewer, writes, Idempotency-Key). + # Required: org, namespace, owner_email. + def register(body = nil, request_options: nil, **fields) + call_op("namespace.register", body, fields, request_options) + end + + # `namespace.register_category` (writer, writes, experimental). + # Register a category in a namespace. Its description + summary are + # Required: org, namespace, name. + def register_category(body = nil, request_options: nil, **fields) + call_op("namespace.register_category", body, fields, request_options) + end + + # `namespace.register_ontology` (admin, writes, Idempotency-Key). + # Register an entity type or relation verb for a namespace. + # Required: org, namespace, kind, name. + def register_ontology(body = nil, request_options: nil, **fields) + call_op("namespace.register_ontology", body, fields, request_options) + end + + # `namespace.restore` (viewer, writes, Idempotency-Key, experimental). + # Restore a snapshot payload into a target namespace. + # Required: org, target_namespace, payload. + def restore(body = nil, request_options: nil, **fields) + call_op("namespace.restore", body, fields, request_options) + end + + # `namespace.rollback` (admin, writes, experimental). + # Return every memory head in a namespace to the version it had at + # Required: org, namespace, as_of. + def rollback(body = nil, request_options: nil, **fields) + call_op("namespace.rollback", body, fields, request_options) + end + + # `namespace.search_categories` (viewer, read-only, experimental). + # Required: org, namespace, query. + def search_categories(body = nil, request_options: nil, **fields) + call_op("namespace.search_categories", body, fields, request_options) + end + + # `namespace.snapshot` (admin, writes, Idempotency-Key, experimental). + # Freeze a namespace's curated state as a portable JSON payload. + # Required: org, namespace. + def snapshot(body = nil, request_options: nil, **fields) + call_op("namespace.snapshot", body, fields, request_options) + end + + # `namespace.summary` (viewer, read-only). + # Aggregated read-only metadata for one namespace, for a single-shot + # Required: org, namespace. + def summary(body = nil, request_options: nil, **fields) + call_op("namespace.summary", body, fields, request_options) + end + + # `namespace.taxonomy` (viewer, read-only). + # The de-facto taxonomy of a namespace — tags + entities across its + # Required: org, namespace. + def taxonomy(body = nil, request_options: nil, **fields) + call_op("namespace.taxonomy", body, fields, request_options) + end + + # `namespace.tune` (viewer, read-only, experimental). + # Draft changes to a namespace's extraction rules, categories and guide from what + # Required: org, namespace. + def tune(body = nil, request_options: nil, **fields) + call_op("namespace.tune", body, fields, request_options) + end + + # `namespace.validate` (viewer, read-only). + # Integrity report for one namespace, in one call, shaped for the agent + # Required: org, namespace. + def validate(body = nil, request_options: nil, **fields) + call_op("namespace.validate", body, fields, request_options) + end + end + + # The `observe.*` operations. + class ObserveOps < OpGroup + # `observe.crystallize` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent. + def crystallize(body = nil, request_options: nil, **fields) + call_op("observe.crystallize", body, fields, request_options) + end + + # `observe.record` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent, tool_name. + def record(body = nil, request_options: nil, **fields) + call_op("observe.record", body, fields, request_options) + end + end + + # The `ops.*` operations. + class OpsOps < OpGroup + # `ops.capabilities` (viewer, read-only). + # Identity is optional: a client discovers the surface with whatever + def capabilities(body = nil, request_options: nil, **fields) + call_op("ops.capabilities", body, fields, request_options) + end + + # `ops.health` (org_admin, writes, Idempotency-Key). + # Required: org. + def health(body = nil, request_options: nil, **fields) + call_op("ops.health", body, fields, request_options) + end + + # `ops.projection_failures.list` (org_admin, writes, Idempotency-Key, experimental). + # Required: org. + def projection_failures_list(body = nil, request_options: nil, **fields) + call_op("ops.projection_failures.list", body, fields, request_options) + end + + # `ops.projection_failures.resolve` (org_admin, writes, Idempotency-Key, experimental). + # Required: org, failure_ids. + def projection_failures_resolve(body = nil, request_options: nil, **fields) + call_op("ops.projection_failures.resolve", body, fields, request_options) + end + + # `ops.projection_failures.retry` (org_admin, writes, Idempotency-Key, experimental). + # Required: org. + def projection_failures_retry(body = nil, request_options: nil, **fields) + call_op("ops.projection_failures.retry", body, fields, request_options) + end + end + + # The `org.*` operations. + class OrgOps < OpGroup + # `org.model_calls` (org_admin, writes, Idempotency-Key, experimental). + # Required: org. + def model_calls(body = nil, request_options: nil, **fields) + call_op("org.model_calls", body, fields, request_options) + end + + # `org.set_model_calls` (org_admin, writes, Idempotency-Key, experimental). + # Required: org, enabled. + def set_model_calls(body = nil, request_options: nil, **fields) + call_op("org.set_model_calls", body, fields, request_options) + end + end + + # The `policy.*` operations. + class PolicyOps < OpGroup + # `policy.check` (viewer, read-only). + # A hypothetical call: what would the rules decide right now? + # Required: org, namespace, operation. + def check(body = nil, request_options: nil, **fields) + call_op("policy.check", body, fields, request_options) + end + + # `policy.decisions` (viewer, read-only, experimental). + # Required: org, namespace. + def decisions(body = nil, request_options: nil, **fields) + call_op("policy.decisions", body, fields, request_options) + end + + # `policy.delete` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, policy_id. + def delete(body = nil, request_options: nil, **fields) + call_op("policy.delete", body, fields, request_options) + end + + # `policy.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("policy.list", body, fields, request_options) + end + + # `policy.set` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, policy_id, effect, actions, condition. + def set(body = nil, request_options: nil, **fields) + call_op("policy.set", body, fields, request_options) + end + end + + # The `procedure.*` operations. + class ProcedureOps < OpGroup + # `procedure.add` (writer, writes). + # Required: org, namespace, name, situation, steps. + def add(body = nil, request_options: nil, **fields) + call_op("procedure.add", body, fields, request_options) + end + + # `procedure.evolve` (writer, writes, experimental). + # Required: org, namespace, memory_key. + def evolve(body = nil, request_options: nil, **fields) + call_op("procedure.evolve", body, fields, request_options) + end + + # `procedure.fork` (writer, writes, experimental). + # Copy a procedure from a namespace the caller can read into the + # Required: org, namespace, from_namespace, memory_key. + def fork(body = nil, request_options: nil, **fields) + call_op("procedure.fork", body, fields, request_options) + end + + # `procedure.list` (viewer, read-only, experimental). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("procedure.list", body, fields, request_options) + end + + # `procedure.locate` (viewer, read-only, experimental). + # Required: org, namespace, memory_key. + def locate(body = nil, request_options: nil, **fields) + call_op("procedure.locate", body, fields, request_options) + end + + # `procedure.match` (viewer, read-only). + # Required: org, namespace, situation. + def match(body = nil, request_options: nil, **fields) + call_op("procedure.match", body, fields, request_options) + end + + # `procedure.record_run` (writer, writes, experimental). + # Required: org, namespace, memory_key. + def record_run(body = nil, request_options: nil, **fields) + call_op("procedure.record_run", body, fields, request_options) + end + + # `procedure.revise` (writer, writes, experimental). + # Required: org, namespace, memory_key, graph. + def revise(body = nil, request_options: nil, **fields) + call_op("procedure.revise", body, fields, request_options) + end + end + + # The `profile.*` operations. + class ProfileOps < OpGroup + # `profile.activity` (viewer, read-only). + # Recent profile reads per agent — "which AI client read my profile, when?". + # Required: org, namespace, agent. + def activity(body = nil, request_options: nil, **fields) + call_op("profile.activity", body, fields, request_options) + end + + # `profile.append` (writer, writes, experimental). + # Required: org, namespace, agent, label, addition. + def append(body = nil, request_options: nil, **fields) + call_op("profile.append", body, fields, request_options) + end + + # `profile.render` (viewer, read-only). + # Render every section in (org, namespace) into one prompt fragment. + # Required: org, namespace, agent. + def render(body = nil, request_options: nil, **fields) + call_op("profile.render", body, fields, request_options) + end + + # `profile.replace` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, label, old, new. + def replace(body = nil, request_options: nil, **fields) + call_op("profile.replace", body, fields, request_options) + end + + # `profile.set` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, label, value. + def set(body = nil, request_options: nil, **fields) + call_op("profile.set", body, fields, request_options) + end + + # `profile.structured` (viewer, read-only, experimental). + # Required: org, namespace, agent. + def structured(body = nil, request_options: nil, **fields) + call_op("profile.structured", body, fields, request_options) + end + end + + # The `profile_schema.*` operations. + class ProfileSchemaOps < OpGroup + # `profile_schema.clear` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace. + def clear(body = nil, request_options: nil, **fields) + call_op("profile_schema.clear", body, fields, request_options) + end + + # `profile_schema.get` (viewer, read-only, experimental). + # Required: org, namespace. + def get(body = nil, request_options: nil, **fields) + call_op("profile_schema.get", body, fields, request_options) + end + + # `profile_schema.set` (admin, writes, Idempotency-Key, experimental). + # Required: org, namespace, json_schema. + def set(body = nil, request_options: nil, **fields) + call_op("profile_schema.set", body, fields, request_options) + end + end + + # The `run.*` operations. + class RunOps < OpGroup + # `run.begin` (writer, writes, Idempotency-Key). + # Required: org, namespace, agent, goal. + def begin(body = nil, request_options: nil, **fields) + call_op("run.begin", body, fields, request_options) + end + + # `run.complete` (writer, writes). + # Required: org, namespace, run_id, status. + def complete(body = nil, request_options: nil, **fields) + call_op("run.complete", body, fields, request_options) + end + + # `run.get` (viewer, read-only). + # Required: org, namespace, run_id. + def get(body = nil, request_options: nil, **fields) + call_op("run.get", body, fields, request_options) + end + + # `run.grade` (writer, writes, Idempotency-Key, experimental). + # A verdict on a CLOSED run, usually days after it — + # Required: org, namespace, grade. + def grade(body = nil, request_options: nil, **fields) + call_op("run.grade", body, fields, request_options) + end + + # `run.list` (viewer, read-only). + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("run.list", body, fields, request_options) + end + end + + # The `search.*` operations. + class SearchOps < OpGroup + # `search.query` (viewer, read-only, experimental). + # Search every plane of the caller's Loom content in one call. + # Required: org, namespace, query. + def query(body = nil, request_options: nil, **fields) + call_op("search.query", body, fields, request_options) + end + end + + # The `session.*` operations. + class SessionOps < OpGroup + # `session.brief_delete` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, brief_key. + def brief_delete(body = nil, request_options: nil, **fields) + call_op("session.brief_delete", body, fields, request_options) + end + + # `session.brief_get` (viewer, read-only, experimental). + # Load a brief: by `brief_key`, else the newest brief a given session + # Required: org, namespace, agent. + def brief_get(body = nil, request_options: nil, **fields) + call_op("session.brief_get", body, fields, request_options) + end + + # `session.brief_list` (viewer, read-only, experimental). + # Required: org, namespace, agent. + def brief_list(body = nil, request_options: nil, **fields) + call_op("session.brief_list", body, fields, request_options) + end + + # `session.brief_save` (writer, writes, Idempotency-Key, experimental). + # Revise (or start) one brief. Give `events` (what happened since the + # Required: org, namespace, agent. + def brief_save(body = nil, request_options: nil, **fields) + call_op("session.brief_save", body, fields, request_options) + end + end + + # The `task.*` operations. + class TaskOps < OpGroup + # `task.accept` (writer, writes, experimental). + # Required: org, namespace, task_id. + def accept(body = nil, request_options: nil, **fields) + call_op("task.accept", body, fields, request_options) + end + + # `task.block` (writer, writes, experimental). + # Required: org, namespace, task_id, fence, reason. + def block(body = nil, request_options: nil, **fields) + call_op("task.block", body, fields, request_options) + end + + # `task.cancel` (writer, writes, experimental). + # A transition anyone entitled may make, with a reason; ``fence`` is + # Required: org, namespace, task_id, reason. + def cancel(body = nil, request_options: nil, **fields) + call_op("task.cancel", body, fields, request_options) + end + + # `task.claim` (writer, writes, experimental). + # Required: org, namespace, task_id. + def claim(body = nil, request_options: nil, **fields) + call_op("task.claim", body, fields, request_options) + end + + # `task.complete` (writer, writes, experimental). + # Required: org, namespace, task_id, fence. + def complete(body = nil, request_options: nil, **fields) + call_op("task.complete", body, fields, request_options) + end + + # `task.counts` (viewer, read-only, experimental). + # Required: org, namespace. + def counts(body = nil, request_options: nil, **fields) + call_op("task.counts", body, fields, request_options) + end + + # `task.create` (writer, writes, Idempotency-Key, experimental). + # ``namespace`` is the poster's own namespace; ``inbox`` the target. + # Required: org, namespace, inbox, kind, title. + def create(body = nil, request_options: nil, **fields) + call_op("task.create", body, fields, request_options) + end + + # `task.defer` (writer, writes, experimental). + # Required: org, namespace, task_id, fence, reason. + def defer(body = nil, request_options: nil, **fields) + call_op("task.defer", body, fields, request_options) + end + + # `task.fail` (writer, writes, experimental). + # Required: org, namespace, task_id, fence, reason. + def fail(body = nil, request_options: nil, **fields) + call_op("task.fail", body, fields, request_options) + end + + # `task.get` (viewer, read-only, experimental). + # Required: org, namespace, task_id. + def get(body = nil, request_options: nil, **fields) + call_op("task.get", body, fields, request_options) + end + + # `task.heartbeat` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, task_id, fence. + def heartbeat(body = nil, request_options: nil, **fields) + call_op("task.heartbeat", body, fields, request_options) + end + + # `task.history` (viewer, read-only, experimental). + # Required: org, namespace, task_id. + def history(body = nil, request_options: nil, **fields) + call_op("task.history", body, fields, request_options) + end + + # `task.list` (viewer, read-only, experimental). + # Tasks in ``inbox`` (owner side) or, with ``posted_by_me``, the tasks + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("task.list", body, fields, request_options) + end + + # `task.progress` (writer, writes, experimental). + # Required: org, namespace, task_id, fence, note. + def progress(body = nil, request_options: nil, **fields) + call_op("task.progress", body, fields, request_options) + end + + # `task.pull` (writer, writes, experimental). + # ``namespace`` is the inbox's owner namespace; the caller must be a + # Required: org, namespace, inbox. + def pull(body = nil, request_options: nil, **fields) + call_op("task.pull", body, fields, request_options) + end + + # `task.reassign` (writer, writes, experimental). + # Required: org, namespace, task_id, to_inbox, reason. + def reassign(body = nil, request_options: nil, **fields) + call_op("task.reassign", body, fields, request_options) + end + + # `task.reopen` (writer, writes, experimental). + # A transition anyone entitled may make, with a reason; ``fence`` is + # Required: org, namespace, task_id, reason. + def reopen(body = nil, request_options: nil, **fields) + call_op("task.reopen", body, fields, request_options) + end + + # `task.resume` (writer, writes, experimental). + # A deferred task back to ``todo`` now, ahead of its ``resume_at``. + # Required: org, namespace, task_id. + def resume(body = nil, request_options: nil, **fields) + call_op("task.resume", body, fields, request_options) + end + + # `task.unblock` (writer, writes, experimental). + # Required: org, namespace, task_id. + def unblock(body = nil, request_options: nil, **fields) + call_op("task.unblock", body, fields, request_options) + end + + # `task.update` (writer, writes, experimental). + # Edit the brief. ``if_match_version`` must equal the current row's + # Required: org, namespace, task_id, if_match_version. + def update(body = nil, request_options: nil, **fields) + call_op("task.update", body, fields, request_options) + end + + # `task.updates` (viewer, read-only, experimental). + # The sender's cursor: events on tasks this caller posted (or, with + # Required: org, namespace. + def updates(body = nil, request_options: nil, **fields) + call_op("task.updates", body, fields, request_options) + end + + # `task.wont_do` (writer, writes, experimental). + # A transition anyone entitled may make, with a reason; ``fence`` is + # Required: org, namespace, task_id, reason. + def wont_do(body = nil, request_options: nil, **fields) + call_op("task.wont_do", body, fields, request_options) + end + end + + # The `tracker.*` operations. + class TrackerOps < OpGroup + # `tracker.answer` (viewer, read-only, experimental). + # Answer a tracker question in prose — or from an artefact's + # Required: namespace. + def answer(body = nil, request_options: nil, **fields) + call_op("tracker.answer", body, fields, request_options) + end + + # `tracker.binding` (viewer, read-only, experimental). + # What this namespace may ask the tracker plane: a QA + # Required: namespace. + def binding(body = nil, request_options: nil, **fields) + call_op("tracker.binding", body, fields, request_options) + end + + # `tracker.component` (viewer, read-only, experimental). + # One component's risk snapshot and its open issues, most severe first. + # Required: namespace, component. + def component(body = nil, request_options: nil, **fields) + call_op("tracker.component", body, fields, request_options) + end + + # `tracker.contract` (viewer, read-only, experimental). + # The record contract as the register page shows it before anyone + # Required: org. + def contract(body = nil, request_options: nil, **fields) + call_op("tracker.contract", body, fields, request_options) + end + + # `tracker.duplicate_check` (viewer, read-only, experimental). + # Does this draft already exist? Give the draft as a + # Required: namespace. + def duplicate_check(body = nil, request_options: nil, **fields) + call_op("tracker.duplicate_check", body, fields, request_options) + end + + # `tracker.flaky` (viewer, read-only, experimental). + # Is this test a known flaky? The flaky-test issues that name it. With + # Required: namespace, test_name. + def flaky(body = nil, request_options: nil, **fields) + call_op("tracker.flaky", body, fields, request_options) + end + + # `tracker.item` (viewer, read-only, experimental). + # The tracker record of up to ten issue / PR numbers: component, severity, + # Required: namespace, numbers. + def item(body = nil, request_options: nil, **fields) + call_op("tracker.item", body, fields, request_options) + end + + # `tracker.links` (viewer, read-only, experimental). + # Which PR probably fixed this issue — or which issue this PR probably + # Required: namespace. + def links(body = nil, request_options: nil, **fields) + call_op("tracker.links", body, fields, request_options) + end + + # `tracker.release` (viewer, read-only, experimental). + # Release readiness for one version (`26.3`): the blocker rows with + # Required: namespace, version. + def release(body = nil, request_options: nil, **fields) + call_op("tracker.release", body, fields, request_options) + end + + # `tracker.similar` (viewer, read-only, experimental). + # The reports that already say it: duplicate and + # Required: namespace. + def similar(body = nil, request_options: nil, **fields) + call_op("tracker.similar", body, fields, request_options) + end + + # `tracker.source.add` (viewer, writes, experimental). + # Register a tracker source: a ClickHouse endpoint and database + # Required: org, name, host, database, user, password, namespaces. + def source_add(body = nil, request_options: nil, **fields) + call_op("tracker.source.add", body, fields, request_options) + end + + # `tracker.source.check` (viewer, read-only, experimental). + # Run the record-contract check on a configured tracker source now: + # Required: org, name. + def source_check(body = nil, request_options: nil, **fields) + call_op("tracker.source.check", body, fields, request_options) + end + + # `tracker.source.inspect` (viewer, read-only, experimental). + # Connect with a read-only credential and say what the + # Required: org. + def source_inspect(body = nil, request_options: nil, **fields) + call_op("tracker.source.inspect", body, fields, request_options) + end + + # `tracker.source.list` (viewer, read-only, experimental). + # The tracker sources of an org: every configured source with + # Required: org. + def source_list(body = nil, request_options: nil, **fields) + call_op("tracker.source.list", body, fields, request_options) + end + + # `tracker.source.remove` (viewer, writes, Idempotency-Key, experimental). + # Retire a registered tracker source and its namespaces. An admin of + # Required: org, name, confirm. + def source_remove(body = nil, request_options: nil, **fields) + call_op("tracker.source.remove", body, fields, request_options) + end + + # `tracker.source.rotate` (viewer, writes, experimental). + # Replace a registered source's credential. An admin of every one + # Required: org, name, user, password. + def source_rotate(body = nil, request_options: nil, **fields) + call_op("tracker.source.rotate", body, fields, request_options) + end + + # `tracker.source.set_mapping` (viewer, writes, Idempotency-Key, experimental). + # Change a registered tracker's mapping, with the same + # Required: org, name. + def source_set_mapping(body = nil, request_options: nil, **fields) + call_op("tracker.source.set_mapping", body, fields, request_options) + end + + # `tracker.test_signal` (viewer, read-only, experimental). + # Flaky, regression or infrastructure? One test's own CI history from + # Required: namespace, test_name. + def test_signal(body = nil, request_options: nil, **fields) + call_op("tracker.test_signal", body, fields, request_options) + end + end + + # The `ui.*` operations. + class UiOps < OpGroup + # `ui.vitals` (viewer, writes, Idempotency-Key, experimental). + # Required: org, namespace, route. + def vitals(body = nil, request_options: nil, **fields) + call_op("ui.vitals", body, fields, request_options) + end + end + + # The `webhook.*` operations. + class WebhookOps < OpGroup + # `webhook.deliveries` (admin, writes, Idempotency-Key, experimental). + # The namespace's webhook events of the last 3 days and their delivery state. + # Required: org, namespace. + def deliveries(body = nil, request_options: nil, **fields) + call_op("webhook.deliveries", body, fields, request_options) + end + + # `webhook.list` (admin, writes, Idempotency-Key, experimental). + # The namespace's memory webhooks. + # Required: org, namespace. + def list(body = nil, request_options: nil, **fields) + call_op("webhook.list", body, fields, request_options) + end + + # `webhook.register` (admin, writes, Idempotency-Key, experimental). + # Register a URL that is told when memory in the namespace changes. + # Required: org, namespace, url, secret_ref. + def register(body = nil, request_options: nil, **fields) + call_op("webhook.register", body, fields, request_options) + end + + # `webhook.remove` (admin, writes, Idempotency-Key, experimental). + # Remove one memory webhook; none of its events is sent after the call, save a + # Required: org, namespace, webhook_id. + def remove(body = nil, request_options: nil, **fields) + call_op("webhook.remove", body, fields, request_options) + end + end + + # The `working_memory.*` operations. + class WorkingMemoryOps < OpGroup + # `working_memory.append` (writer, writes, experimental). + # Append text to a working-memory block, creating it when missing. + # Required: org, namespace, agent, addition. + def append(body = nil, request_options: nil, **fields) + call_op("working_memory.append", body, fields, request_options) + end + + # `working_memory.delete` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent. + def delete(body = nil, request_options: nil, **fields) + call_op("working_memory.delete", body, fields, request_options) + end + + # `working_memory.get` (viewer, read-only, experimental). + # Required: org, namespace, agent. + def get(body = nil, request_options: nil, **fields) + call_op("working_memory.get", body, fields, request_options) + end + + # `working_memory.render` (viewer, read-only). + # Required: org, namespace, agent. + def render(body = nil, request_options: nil, **fields) + call_op("working_memory.render", body, fields, request_options) + end + + # `working_memory.replace` (writer, writes, Idempotency-Key, experimental). + # Required: org, namespace, agent, old. + def replace(body = nil, request_options: nil, **fields) + call_op("working_memory.replace", body, fields, request_options) + end + + # `working_memory.set` (writer, writes, Idempotency-Key). + # Overwrite one working-memory block. + # Required: org, namespace, agent. + def set(body = nil, request_options: nil, **fields) + call_op("working_memory.set", body, fields, request_options) + end + end + + # The class of each op group, by name. + GROUPS = { + "admin" => AdminOps, + "agents" => AgentsOps, + "assistant" => AssistantOps, + "audit" => AuditOps, + "blacklist" => BlacklistOps, + "calibration" => CalibrationOps, + "code" => CodeOps, + "collection" => CollectionOps, + "conflicts" => ConflictsOps, + "connection" => ConnectionOps, + "consolidations" => ConsolidationsOps, + "context" => ContextOps, + "conversation" => ConversationOps, + "cost" => CostOps, + "decision" => DecisionOps, + "erasure" => ErasureOps, + "extraction_policy" => ExtractionPolicyOps, + "facts" => FactsOps, + "grants" => GrantsOps, + "help" => HelpOps, + "inbox" => InboxOps, + "insights" => InsightsOps, + "knowledge" => KnowledgeOps, + "learnings" => LearningsOps, + "memory" => MemoryOps, + "memory_schema" => MemorySchemaOps, + "mentor" => MentorOps, + "namespace" => NamespaceOps, + "observe" => ObserveOps, + "ops" => OpsOps, + "org" => OrgOps, + "policy" => PolicyOps, + "procedure" => ProcedureOps, + "profile" => ProfileOps, + "profile_schema" => ProfileSchemaOps, + "run" => RunOps, + "search" => SearchOps, + "session" => SessionOps, + "task" => TaskOps, + "tracker" => TrackerOps, + "ui" => UiOps, + "webhook" => WebhookOps, + "working_memory" => WorkingMemoryOps, + }.freeze + + # One accessor per op group on the client: `client.memory`, `client.task`, ... + module GroupAccessors + def admin + op_group("admin") + end + + def agents + op_group("agents") + end + + def assistant + op_group("assistant") + end + + def audit + op_group("audit") + end + + def blacklist + op_group("blacklist") + end + + def calibration + op_group("calibration") + end + + def code + op_group("code") + end + + def collection + op_group("collection") + end + + def conflicts + op_group("conflicts") + end + + def connection + op_group("connection") + end + + def consolidations + op_group("consolidations") + end + + def context + op_group("context") + end + + def conversation + op_group("conversation") + end + + def cost + op_group("cost") + end + + def decision + op_group("decision") + end + + def erasure + op_group("erasure") + end + + def extraction_policy + op_group("extraction_policy") + end + + def facts + op_group("facts") + end + + def grants + op_group("grants") + end + + def help + op_group("help") + end + + def inbox + op_group("inbox") + end + + def insights + op_group("insights") + end + + def knowledge + op_group("knowledge") + end + + def learnings + op_group("learnings") + end + + def memory + op_group("memory") + end + + def memory_schema + op_group("memory_schema") + end + + def mentor + op_group("mentor") + end + + def namespace + op_group("namespace") + end + + def observe + op_group("observe") + end + + def ops + op_group("ops") + end + + def org + op_group("org") + end + + def policy + op_group("policy") + end + + def procedure + op_group("procedure") + end + + def profile + op_group("profile") + end + + def profile_schema + op_group("profile_schema") + end + + def run + op_group("run") + end + + def search + op_group("search") + end + + def session + op_group("session") + end + + def task + op_group("task") + end + + def tracker + op_group("tracker") + end + + def ui + op_group("ui") + end + + def webhook + op_group("webhook") + end + + def working_memory + op_group("working_memory") + end + end + end + end +end diff --git a/tests/unit/test_sdk_rb_generated.py b/tests/unit/test_sdk_rb_generated.py new file mode 100644 index 0000000000..6c68fef550 --- /dev/null +++ b/tests/unit/test_sdk_rb_generated.py @@ -0,0 +1,62 @@ +"""The Ruby SDK's operation table, per-op methods and error classes are generated from +the registry and the server's error codes; this fails when a checked-in file is stale.""" + +from __future__ import annotations + +from collections.abc import Callable +from dataclasses import replace +from pathlib import Path + +import pytest + +from scripts.codegen import sdk_rb_gen +from server.operations.registry import ALL_OPERATIONS + + +@pytest.mark.parametrize( + "target,build", sdk_rb_gen.TARGETS, ids=lambda t: getattr(t, "display", "") +) +def test_generated_ruby_file_is_current( + target: sdk_rb_gen.GeneratedFile, build: Callable[[], str] +) -> None: + assert target.is_current(build()), f"{target.display} is stale: run {sdk_rb_gen.COMMAND}" + + +def test_check_mode_reports_a_stale_file( + tmp_path: Path, capsys: pytest.CaptureFixture[str] +) -> None: + target, build = sdk_rb_gen.TARGETS[0] + stale = replace(target, path=tmp_path / "ops.rb") + stale.path.write_text("# an older table\n", encoding="utf-8") + assert stale.sync(build(), check=True) == 1 + assert "is stale: run python scripts/codegen/sdk_rb_gen.py" in capsys.readouterr().err + + +def test_generated_table_covers_every_operation() -> None: + text = (sdk_rb_gen.OUT_DIR / "ops.rb").read_text(encoding="utf-8") + for op in ALL_OPERATIONS: + group, method = sdk_rb_gen.split_op(op.name) + assert f'"{op.name}" => OpSpec.new("{op.name}", "{group}", "{method}",' in text, op.name + assert f"OP_COUNT = {len(ALL_OPERATIONS)}" in text + + +def test_ruby_method_names_follow_the_python_sdk_and_skip_object_methods() -> None: + assert sdk_rb_gen.split_op("tracker.source.add") == ("tracker", "source_add") + assert sdk_rb_gen.split_op("memory.import") == ("memory", "import") + assert sdk_rb_gen.split_op("memory.inspect") == ("memory", "inspect_") + + +def test_an_error_class_never_hides_a_constant_the_gem_relies_on() -> None: + names = {name for _code, name, *_ in sdk_rb_gen.error_codes()} + assert not names & sdk_rb_gen.RESERVED_CONSTANTS + + +def test_every_documented_error_code_has_a_class() -> None: + from scripts.codegen.docs_reference import render_errors + + documented = {line[6:-1] for line in render_errors().splitlines() if line.startswith("#### `")} + classes = {code for code, *_ in sdk_rb_gen.error_codes()} + assert documented == classes + assert ("PINNED_CONFLICT", "PinnedConflict") in { + (c, n) for c, n, *_ in sdk_rb_gen.error_codes() + } From 8c7e86f4b610c8eeeba6d90c0fb4b3c62ac89045 Mon Sep 17 00:00:00 2001 From: rahulsjha <132360698+rahulsjha@users.noreply.github.com> Date: Sun, 22 Nov 2026 02:23:29 +0530 Subject: [PATCH 2/4] Ruby SDK: generated op groups, Loom.configure, retries and error classes client..(**fields) calls every served op with the bound org, namespace and agent, a keyword of the same name overriding one per call, and an unknown field refused before sending. Loom.configure and LOOM_BASE_URL / LOOM_API_KEY set the defaults. Calls follow the TypeScript SDK's retry rules: one Idempotency-Key per deduplicated op, repeated on every resend; 408/5xx resent for idempotent ops; Retry-After (seconds or HTTP-date) honoured; a 429 waited out within rate_limit_max_wait. A server code raises its own Error subclass (Loom::PinnedConflict, Loom::RateLimited, ...). The existing set/get/search/delete methods keep their typed answers. Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com> --- sdk/ruby/README.md | 143 +++++++++--- sdk/ruby/clickhouse-loom.gemspec | 7 +- sdk/ruby/lib/clickhouse/loom.rb | 4 + sdk/ruby/lib/clickhouse/loom/client.rb | 210 ++++++++++++++---- sdk/ruby/lib/clickhouse/loom/configuration.rb | 50 +++++ sdk/ruby/lib/clickhouse/loom/errors.rb | 63 ++++-- sdk/ruby/lib/clickhouse/loom/operations.rb | 58 +++++ sdk/ruby/lib/clickhouse/loom/retry_policy.rb | 109 +++++++++ sdk/ruby/test/configuration_test.rb | 67 ++++++ sdk/ruby/test/errors_test.rb | 45 ++++ sdk/ruby/test/fake_server.rb | 17 +- sdk/ruby/test/generated_test.rb | 140 ++++++++++++ sdk/ruby/test/retry_test.rb | 204 +++++++++++++++++ sdk/ruby/test/test_helper.rb | 8 +- 14 files changed, 1030 insertions(+), 95 deletions(-) create mode 100644 sdk/ruby/lib/clickhouse/loom/configuration.rb create mode 100644 sdk/ruby/lib/clickhouse/loom/operations.rb create mode 100644 sdk/ruby/lib/clickhouse/loom/retry_policy.rb create mode 100644 sdk/ruby/test/configuration_test.rb create mode 100644 sdk/ruby/test/generated_test.rb create mode 100644 sdk/ruby/test/retry_test.rb diff --git a/sdk/ruby/README.md b/sdk/ruby/README.md index 6731b49d16..f3c315cd2b 100644 --- a/sdk/ruby/README.md +++ b/sdk/ruby/README.md @@ -1,8 +1,10 @@ # Loom Ruby client -A minimal Ruby client for [ClickHouse Loom](https://clickhouse.github.io/loom/)'s memory -operations: `memory.set`, `memory.get`, `memory.search` and `memory.delete`. It depends on -the standard library only (`net/http` and `json`) and needs Ruby 3.1 or later. +A Ruby client for [ClickHouse Loom](https://clickhouse.github.io/loom/). Every operation +the server serves is a method, generated from the server's registry +(`client.memory.set(...)`, `client.task.create(...)`), so a new operation reaches the gem +by regeneration alone. It depends on the standard library only (`net/http` and `json`) +and needs Ruby 3.1 or later. The gem is named `clickhouse-loom`. Build and install it from a checkout: @@ -10,10 +12,6 @@ The gem is named `clickhouse-loom`. Build and install it from a checkout: cd sdk/ruby && gem build clickhouse-loom.gemspec && gem install clickhouse-loom-*.gem ``` -The full surface (every operation, typed from the server's registry) is in the -[Python](https://github.com/ClickHouse/loom/tree/main/sdk/python) and -[TypeScript](https://github.com/ClickHouse/loom/tree/main/sdk/typescript) SDKs. - ## Example Against a @@ -24,30 +22,69 @@ on this machine (`http://localhost:7777`, org `dev`, namespace `local`, no token require "clickhouse/loom" loom = ClickHouse::Loom::Client.new(org: "dev", namespace: "local", agent: "assistant") -loom.set("deploy_window", "Deploys run Tue and Thu only.") -puts loom.get("deploy_window").value # Deploys run Tue and Thu only. -puts loom.search("when do we deploy?").results.first.memory_key -loom.delete("deploy_window") +loom.memory.set(memory_key: "deploy_window", value: "Deploys run Tue and Thu only.") +puts loom.memory.get(memory_key: "deploy_window")["value"] # Deploys run Tue and Thu only. +puts loom.memory.search(query: "when do we deploy?")["results"].first["memory_key"] +loom.memory.delete(memory_key: "deploy_window") ``` +`Loom` is the short name of `ClickHouse::Loom` (`Loom::Client`, `Loom.configure`) unless +your application already defines a `Loom` of its own. + ## Configuration -`ClickHouse::Loom::Client.new(...)` binds the server and the identity once; every call sends -the org, namespace and agent in its body. +Set the defaults once, in a Rails initializer for example: + +```ruby +Loom.configure do |c| + c.base_url = "https://loom.example.com" + c.api_key = ENV.fetch("LOOM_API_KEY") + c.org = "acme" + c.namespace = "support" + c.agent = "rails-app" +end + +client = Loom::Client.new # takes every default above +client = Loom::Client.new(namespace: "user-42") # an argument wins over the configured value +``` -| Argument | Default | -| ------------------------------ | --------------------------------------------------------------- | -| `base_url` | `LOOM_BASE_URL`, else `http://localhost:7777` | -| `api_key` | `LOOM_API_KEY`; with neither, no `Authorization` header | -| `org`, `namespace`, `agent` | Left out of the body when blank, so the server's defaults apply | -| `open_timeout`, `read_timeout` | 10 and 60 seconds | +| Setting | Default | +| ------------------------------ | ---------------------------------------------------------------------------- | +| `base_url` | `LOOM_BASE_URL`, else `http://localhost:7777` | +| `api_key` | `LOOM_API_KEY`; with neither, no `Authorization` header | +| `org`, `namespace`, `agent` | Left out of the body when blank, so the server's defaults apply | +| `open_timeout`, `read_timeout` | 10 and 60 seconds | +| `retry_policy` | `{ max_attempts: 3, backoff: 0.25, ... }` (see [Retries](#retries)) | +| `rate_limit_max_wait` | 15 seconds of waiting out `429` answers per call; `0` raises the first `429` | -The client sends one request per call and never retries. It does not follow redirects, so a -memory body and token never go to another origin: a 3xx answer raises a -`ClickHouse::Loom::Error`. +An argument to `Client.new` wins over `Loom.configure`, which wins over the environment. ## Calls +`client..(**fields)` posts `/v1/.`: the group is the op name's +first segment and the method is the rest with `.` turned into `_`, as in the Python SDK +(`tracker.source.add` is `client.tracker.source_add`). A method that would shadow a method +every Ruby object has takes a trailing underscore (`memory.inspect` is +`client.memory.inspect_`). Each method returns the decoded JSON answer as a Hash. + +- The fields are keywords. The bound `org`, `namespace` and `agent` are sent with every + call, and a keyword of the same name overrides one for that call: + `client.memory.set(memory_key: "k", value: "v", namespace: "user-42")`. +- A keyword the op does not take raises `ArgumentError` before anything is sent, with the + nearest field name. A `nil` keyword is left out; to send an explicit `null`, pass a Hash + body first: `client.memory.set({ "ttl_seconds" => nil }, memory_key: "k", value: "v")`. +- `request_options:` takes `idempotency_key:` (your own key, for a job that may run twice) + and `retry_policy:` (fields set over the client's policy for this call). +- `Loom::Generated::OPS` holds every op's spec: idempotency, read-only, role, maturity, + its fields and the required ones. `client.call("some.op", { ... })` calls an op this + version of the gem does not know yet. + +`client.search` with no argument is the `search.*` group (`client.search.query(...)`). + +### Memory shorthands + +The typed memory calls of the first version of the gem remain: + | Call | Answers | | -------------------------------------------------------- | ------------------------------------------------------------------ | | `set(key, value, memory_type: nil, tags: nil)` | `memory_id`, `version`, `content_sha256`, `status`, `noop` | @@ -58,19 +95,60 @@ memory body and token never go to another origin: a 3xx answer raises a `value` is plain text or any Hash, Array or scalar. A missing key is not an error: `get` answers with `found` false. +## Retries + +The retry and idempotency rules of the TypeScript and Python SDKs: + +- An op the server deduplicates (idempotent and not read-only, such as `memory.set`) gets + an `Idempotency-Key`, and every resend of the call repeats it, with the same + `X-Request-Id`. +- A connection that failed before the request went out is resent. +- `408` and `5xx` answers are resent for an op the registry marks idempotent; any other op + only on a `408` or a refusal the server made before running it (`AUTH_UNAVAILABLE`). An + error the server classes `configuration`, and the codes the SDKs never resend, are not. +- A timeout or an answer cut off after sending is resent only for an op the server + deduplicates (`retry_timeouts: :idempotent`; `:never` and `:always` change that). +- The server's `Retry-After` (seconds or an HTTP-date) or `detail.retry_after_s` replaces + the backoff when it is at most `max_retry_after` (60) seconds. +- A `429` is pacing, not a retry: the call waits out `Retry-After` for at most + `rate_limit_max_wait` seconds, then raises `Loom::RateLimited`. + +| `retry_policy` field | Default | +| ------------------------- | ----------------------------------------------------------- | +| `max_attempts` | 3, the first included; 1 disables retries | +| `backoff`, `backoff_max` | 0.25 s doubled per attempt, at most 5 s | +| `backoff_jitter` | 0.5: each sleep is `delay * (1 - jitter/2 + rand * jitter)` | +| `statuses` | `408` and `500` to `599` | +| `retry_connection_errors` | `true` | +| `retry_timeouts` | `:idempotent` | +| `respect_retry_after` | `true`, up to `max_retry_after` (60 s) | +| `total_backoff_budget` | unbounded seconds of sleep per call | + +Not carried over yet: pacing on the `X-RateLimit-*` headers before a `429` arrives, a +per-call timeout, and resending a `401` with a fresh token (the gem takes a fixed +`api_key`). + +The client does not follow redirects, so a memory body and token never go to another +origin: a `3xx` answer raises a `Loom::Error`. + ## Errors -A non-2xx answer raises a `ClickHouse::Loom::Error` carrying the server's `code`, its -`category` (`input`, `auth`, `capacity`, `dependency`, `configuration` or `internal`), -whether resending can succeed (`retryable?`), the wait it asked for in seconds -(`retry_after`), the `request_id` and the HTTP `status`. Match on `code`, never on the +A non-2xx answer raises a `Loom::Error` carrying the server's `code`, its `category` +(`input`, `auth`, `capacity`, `dependency`, `configuration` or `internal`), whether +resending can succeed (`retryable?`), the wait it asked for in seconds (`retry_after`), +the `request_id`, the HTTP `status` and the whole `detail`. Each server code has its own +subclass, generated from the server's code list (`PINNED_CONFLICT` raises +`Loom::PinnedConflict`, `RATE_LIMITED` raises `Loom::RateLimited`); a code this version +does not know raises `Loom::Error` itself. Match on the class or the `code`, never on the message: ```ruby begin - loom.get("deploy_window") -rescue ClickHouse::Loom::Error => e - sleep(e.retry_after || 1) if e.code == "RATE_LIMITED" + client.memory.set(memory_key: "deploy_window", value: "Mondays") +rescue Loom::PinnedConflict => e + client.memory.update(memory_key: "deploy_window", value: "Mondays") # keeps the pin +rescue Loom::RateLimited => e + sleep(e.retry_after || 1) end ``` @@ -79,6 +157,13 @@ answer that is not a JSON object one with `INVALID_RESPONSE`; neither is marked since the call may have run. The codes and what to do about each are in the [errors reference](https://github.com/ClickHouse/loom/blob/main/docs/reference/errors.md). +## Generated files + +`lib/clickhouse/loom/generated/ops.rb` and `errors.rb` are written by +`python scripts/codegen/sdk_rb_gen.py` from the server's registry and error codes; never +edit them by hand. `python scripts/codegen/sdk_rb_gen.py --check` (in `make lint` and the +unit suite) fails when they are stale. + ## Tests ```bash diff --git a/sdk/ruby/clickhouse-loom.gemspec b/sdk/ruby/clickhouse-loom.gemspec index d00e753307..a4a8745289 100644 --- a/sdk/ruby/clickhouse-loom.gemspec +++ b/sdk/ruby/clickhouse-loom.gemspec @@ -5,9 +5,10 @@ require_relative "lib/clickhouse/loom/version" Gem::Specification.new do |spec| spec.name = "clickhouse-loom" spec.version = ClickHouse::Loom::VERSION - spec.summary = "A minimal Ruby client for ClickHouse Loom's memory operations." - spec.description = "Saves, reads, searches and deletes agent memories over Loom's HTTP API, " \ - "with the standard library only." + spec.summary = "A Ruby client for ClickHouse Loom: every operation as a method, generated from the server." + spec.description = "Calls every Loom operation over its HTTP API (client.memory.set, client.task.create, ...) " \ + "with the other SDKs' retry and idempotency rules and an error class per server code, " \ + "using the standard library only." spec.authors = ["ClickHouse"] spec.homepage = "https://github.com/ClickHouse/loom/tree/main/sdk/ruby" spec.license = "Apache-2.0" diff --git a/sdk/ruby/lib/clickhouse/loom.rb b/sdk/ruby/lib/clickhouse/loom.rb index 38a970cf94..f3514ef7f3 100644 --- a/sdk/ruby/lib/clickhouse/loom.rb +++ b/sdk/ruby/lib/clickhouse/loom.rb @@ -3,3 +3,7 @@ require_relative "loom/version" require_relative "loom/errors" require_relative "loom/client" + +# The short name the issue and the docs use (Loom.configure, Loom::RateLimited), unless +# the application already has a Loom of its own. +Loom = ClickHouse::Loom unless Object.const_defined?(:Loom) diff --git a/sdk/ruby/lib/clickhouse/loom/client.rb b/sdk/ruby/lib/clickhouse/loom/client.rb index aa25420f0f..0752c120e7 100644 --- a/sdk/ruby/lib/clickhouse/loom/client.rb +++ b/sdk/ruby/lib/clickhouse/loom/client.rb @@ -3,10 +3,16 @@ require "json" require "net/http" require "openssl" +require "securerandom" require "uri" require_relative "errors" require_relative "version" +require_relative "configuration" +require_relative "retry_policy" +require_relative "operations" +require_relative "generated/errors" +require_relative "generated/ops" module ClickHouse module Loom @@ -32,25 +38,72 @@ module Loom # in the namespace; +tombstoned+ is true when a tombstone was written over one. DeleteResult = Struct.new(:found, :tombstoned, :version, keyword_init: true) - # Calls Loom's memory operations as one org, namespace and agent. + # Calls every Loom operation as one org, namespace and agent. # - # Every operation is POST /v1/ with a JSON body. The org, namespace and agent - # are bound once and sent with every call; a blank one is left out of the body, so - # the server's default applies. The client sends one request per call and never - # retries. It does not follow redirects, so a memory body and token never go to - # another origin: a 3xx answer raises an Error. + # client.memory.set(memory_key: "k", value: "v") posts /v1/memory.set: one method per + # served op, generated from the server's registry (Generated::OPS) and grouped by the + # op name's first segment. The org, namespace and agent are bound once and sent with + # every call; a keyword of the same name overrides one for that call, and a blank one + # is left out of the body, so the server's default applies. set, get, search and + # delete are the hand-written memory calls with typed answers. + # + # A call is resent as RetryPolicy describes, a 429 is waited out, and an op the server + # deduplicates gets one Idempotency-Key that every resend repeats. The client does not + # follow redirects, so a memory body and token never go to another origin: a 3xx + # answer raises an Error. class Client - # base_url: defaults to LOOM_BASE_URL, then DEFAULT_BASE_URL. api_key: defaults to - # LOOM_API_KEY; with neither, no Authorization header is sent, which a server with - # auth off accepts. - def initialize(base_url: nil, api_key: nil, org: nil, namespace: nil, agent: nil, - open_timeout: 10, read_timeout: 60) - @base_url = first_non_blank(base_url, ENV.fetch("LOOM_BASE_URL", nil), DEFAULT_BASE_URL).sub(%r{/+\z}, "") + include Generated::GroupAccessors + + # Raised before the request went out: resending cannot run the op twice. + UNSENT_ERRORS = [Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, Errno::EADDRNOTAVAIL, + SocketError, Net::OpenTimeout].freeze + NETWORK_ERRORS = [SystemCallError, SocketError, IOError, Timeout::Error, Net::ProtocolError, + OpenSSL::SSL::SSLError].freeze + + # The bound identity sent with every call ("org", "namespace", "agent"; blank ones left out). + attr_reader :identity + # The server every call goes to, and the resolved RetryPolicy. + attr_reader :base_url, :retry_policy + + # Each argument left nil takes ClickHouse::Loom.configure's value, then the environment + # (LOOM_BASE_URL, LOOM_API_KEY), then the default: http://localhost:7777 and no + # Authorization header, which a server with auth off accepts. +retry_policy+ is a + # Hash of RetryPolicy fields set over the configured policy ({ max_attempts: 1 } + # disables retries); +rate_limit_max_wait+ is the seconds one call may spend waiting + # out 429 answers (default 15, 0 raises the first). +sleeper+ is called with the + # seconds to wait between attempts (a test seam; default Kernel#sleep). + def initialize(base_url: nil, api_key: nil, org: nil, namespace: nil, agent: nil, open_timeout: nil, + read_timeout: nil, retry_policy: nil, rate_limit_max_wait: nil, sleeper: nil) + config = Loom.configuration + @base_url = first_non_blank(base_url, config.base_url, ENV.fetch("LOOM_BASE_URL", nil), + DEFAULT_BASE_URL).sub(%r{/+\z}, "") # An exported but empty LOOM_API_KEY must not send "Bearer " and turn a clear 401 into a puzzle. - @api_key = first_non_blank(api_key, ENV.fetch("LOOM_API_KEY", nil)) - @identity = { org: org, namespace: namespace, agent: agent }.reject { |_, v| blank?(v) } - @open_timeout = open_timeout - @read_timeout = read_timeout + @api_key = first_non_blank(api_key, config.api_key, ENV.fetch("LOOM_API_KEY", nil)) + @identity = { "org" => first_non_blank(org, config.org), + "namespace" => first_non_blank(namespace, config.namespace), + "agent" => first_non_blank(agent, config.agent) }.compact.freeze + @open_timeout = open_timeout || config.open_timeout || 10 + @read_timeout = read_timeout || config.read_timeout || 60 + @retry_policy = RetryPolicy.resolve(RetryPolicy.default, config.retry_policy, "ClickHouse::Loom.configure") + @retry_policy = RetryPolicy.resolve(@retry_policy, retry_policy, "Client") + @rate_limit_max_wait = Float(rate_limit_max_wait || config.rate_limit_max_wait || 15) + @sleeper = sleeper || ->(seconds) { sleep(seconds) } + @groups = {} + end + + # The ops of one group: client.op_group("memory") is client.memory. + def op_group(name) + @groups[name.to_s] ||= Generated::GROUPS.fetch(name.to_s).new(self) + end + + # Posts +input+ (a Hash) over the bound identity to /v1/ and returns the decoded + # answer. An op the generated table does not know (a newer server) is sent as it is: + # no Idempotency-Key unless one is given, and resent only when it provably never ran. + def call(op, input = nil, idempotency_key: nil, retry_policy: nil) + spec = Generated::OPS[op] + body = JSON.generate(@identity.merge((input || {}).transform_keys(&:to_s))) + policy = RetryPolicy.resolve(@retry_policy, retry_policy, "call #{op}") + send_with_retries(op, spec, body, request_headers(spec, idempotency_key), policy) end # Saves +value+ under +key+: plain text, or any Hash, Array or scalar. Writing a @@ -73,8 +126,11 @@ def get(key) # Ranks the memories that answer +query+. With no agent bound, it reads every # agent's rows in the namespace; with one, only that agent's. +top_k+ left nil lets - # the server use 5; +tags+ keeps only rows carrying any of them. - def search(query, top_k: nil, memory_type: nil, tags: nil) + # the server use 5; +tags+ keeps only rows carrying any of them. With no argument at + # all it is the search.* group (client.search.query(...)), like every other group. + def search(query = nil, top_k: nil, memory_type: nil, tags: nil) + return op_group("search") if [query, top_k, memory_type, tags].all?(&:nil?) + body = { query: query, top_k: top_k, memory_type: memory_type, tags: tags }.compact out = call("memory.search", body) hits = Array(out["results"]).map do |h| @@ -91,39 +147,119 @@ def delete(key) DeleteResult.new(found: out["found"] == true, tombstoned: out["tombstoned"] == true, version: out["version"]) end + # Names the server and the identity, never the token. + def inspect + "#<#{self.class.name} #{@base_url} #{@identity.map { |k, v| "#{k}=#{v}" }.join(" ")}>" + end + private - # Posts +input+ to /v1/ and returns the decoded 2xx answer. - def call(op, input) - response = post(op, JSON.generate(@identity.merge(input))) - request_id = response["X-Request-Id"].to_s - unless response.is_a?(Net::HTTPSuccess) - raise Error.from_response(op, response.code.to_i, response.body, request_id, response["Retry-After"]) + def request_headers(spec, idempotency_key) + headers = { "Content-Type" => "application/json", "Accept" => "application/json", + "User-Agent" => SDK_IDENT, "X-Loom-SDK" => SDK_IDENT, "X-Request-Id" => SecureRandom.uuid } + headers["Authorization"] = "Bearer #{@api_key}" if @api_key + # The server keeps no replay of a read-only op: its resend just runs again. + key = idempotency_key || (SecureRandom.uuid if spec&.deduplicated?) + headers["Idempotency-Key"] = key.to_s if key + headers + end + + # One call: attempts until an answer to return or an error to raise. Every attempt + # sends the same body and headers, so the same Idempotency-Key and X-Request-Id. + def send_with_retries(op, spec, body, headers, policy) + state = { attempt: 1, sent: 0, slept: 0.0, paced: 0.0 } + loop do + headers["X-Loom-Retry-Count"] = state[:sent].to_s + state[:sent] += 1 + response = attempt(op, spec, body, headers, policy, state) + next if response.nil? + return decode(op, response) if response.is_a?(Net::HTTPSuccess) + + # The server's echo of X-Request-Id, else the id this call sent (an error answer may not echo it). + request_id = response["X-Request-Id"] || headers["X-Request-Id"] + error = Error.from_response(op, response.code.to_i, response.body, request_id, + response["Retry-After"], idempotent: spec&.idempotent == true) + next if resend_after_answer?(response, error, spec, policy, state) + + raise error end + end + + # The answer of one attempt, or nil after a connection failure the policy resends. + def attempt(op, spec, body, headers, policy, state) + post(op, body, headers) + rescue *NETWORK_ERRORS => e + # A TLS failure (certificate verification stays on) does not pass by resending. + raise Error.network(op, e) if e.is_a?(OpenSSL::SSL::SSLError) + + unsent = UNSENT_ERRORS.any? { |klass| e.is_a?(klass) } + # A timeout or a cut-off answer may follow a write: resent only where the server dedups. + resend = unsent ? policy.retry_connection_errors : may_rerun?(policy, spec) + # The error raised in the end stays not retryable either way, as before: the call may have run. + raise Error.network(op, e) unless resend && pause_before_next(policy, state, nil) + nil + end + + def resend_after_answer?(response, error, spec, policy, state) + status = response.code.to_i + return wait_out_rate_limit(response, state) if status == 429 + return false unless policy.statuses.include?(status) && !NEVER_RETRIED.key?(error.code) + # Only the server's configuration class stops a resend; retryable false alone does + # not (an INTERNAL_ERROR on an idempotent op is worth one). + return false if error.detail["category"] == "configuration" + return false unless spec&.idempotent || status == 408 || NEVER_RAN_CODES.include?(error.code) + + pause_before_next(policy, state, RetryAfter.parse(response["Retry-After"] || error.detail["retry_after_s"])) + end + + # A 429 is pacing, not a retry: wait the Retry-After (1 s when absent or over 60 s) + # while the call's rate_limit_max_wait allows, and send again. + def wait_out_rate_limit(response, state) + wait = RetryAfter.for_rate_limit(response["Retry-After"]) + return false unless @rate_limit_max_wait.positive? && state[:paced] + wait <= @rate_limit_max_wait + + state[:paced] += wait + @sleeper.call(wait) + true + end + + def may_rerun?(policy, spec) + policy.retry_timeouts == :always || (policy.retry_timeouts == :idempotent && spec&.deduplicated?) + end + + # Sleeps before the next attempt and counts it, or returns false when the policy says + # stop: attempts spent, or the backoff budget. +hint+ is the server's wait in seconds. + def pause_before_next(policy, state, hint) + return false if state[:attempt] >= policy.max_attempts + + delay = policy.backoff_delay(state[:attempt]) + delay = hint if policy.respect_retry_after && hint && hint <= policy.max_retry_after + return false if delay > policy.total_backoff_budget - state[:slept] + + @sleeper.call(delay) + state[:slept] += delay + state[:attempt] += 1 + true + end + + # The decoded 2xx answer. + def decode(op, response) parsed = parse_object(response.body) - raise Error.invalid_response(op, response.code.to_i, response.body, request_id) if parsed.nil? + raise Error.invalid_response(op, response.code.to_i, response.body, response["X-Request-Id"]) if parsed.nil? parsed end - def post(op, body) + def post(op, body, headers) uri = URI("#{@base_url}/v1/#{op}") request = Net::HTTP::Post.new(uri) - request["Content-Type"] = "application/json" - request["Accept"] = "application/json" - request["User-Agent"] = SDK_IDENT - request["X-Loom-SDK"] = SDK_IDENT - request["Authorization"] = "Bearer #{@api_key}" if @api_key + headers.each { |name, value| request[name] = value } request.body = body Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: @open_timeout, read_timeout: @read_timeout) do |http| http.request(request) end - rescue SystemCallError, SocketError, IOError, Timeout::Error, Net::ProtocolError, OpenSSL::SSL::SSLError => e - # No complete answer, or a TLS handshake that failed: the call may have run, so it is not - # marked retryable. Certificate verification stays on. - raise Error.network(op, e) end def parse_object(text) @@ -136,10 +272,6 @@ def parse_object(text) def first_non_blank(*values) values.map { |v| v.to_s.strip }.find { |v| !v.empty? } end - - def blank?(value) - value.to_s.strip.empty? - end end end end diff --git a/sdk/ruby/lib/clickhouse/loom/configuration.rb b/sdk/ruby/lib/clickhouse/loom/configuration.rb new file mode 100644 index 0000000000..69627cdbbb --- /dev/null +++ b/sdk/ruby/lib/clickhouse/loom/configuration.rb @@ -0,0 +1,50 @@ +# frozen_string_literal: true + +module ClickHouse + module Loom + # The process-wide defaults a Client.new without arguments takes, set once with + # ClickHouse::Loom.configure (in Rails, an initializer). An argument to Client.new + # wins over a value set here, and a value set here over LOOM_BASE_URL / LOOM_API_KEY. + class Configuration + # The server and the token; nil falls back to LOOM_BASE_URL / LOOM_API_KEY. + attr_accessor :base_url, :api_key + # The identity every call is sent as; a call can override each one. + attr_accessor :org, :namespace, :agent + # Seconds to wait for the connection and for each answer. + attr_accessor :open_timeout, :read_timeout + # A Hash of RetryPolicy fields set over RetryPolicy.default, like { max_attempts: 5 }. + attr_accessor :retry_policy + # Seconds one call may spend waiting out 429 answers; 0 raises the first one. + attr_accessor :rate_limit_max_wait + + def initialize + @open_timeout = 10 + @read_timeout = 60 + @rate_limit_max_wait = 15 + end + end + + class << self + # The configuration Client.new reads its defaults from. + def configuration + @configuration ||= Configuration.new + end + + # ClickHouse::Loom.configure do |c| + # c.base_url = "https://loom.example.com" + # c.api_key = Rails.application.credentials.loom_api_key + # c.org = "acme" + # c.namespace = "support" + # end + def configure + yield configuration + configuration + end + + # Forgets what configure set (for tests). + def reset_configuration! + @configuration = Configuration.new + end + end + end +end diff --git a/sdk/ruby/lib/clickhouse/loom/errors.rb b/sdk/ruby/lib/clickhouse/loom/errors.rb index 1043d876ce..a79956dd86 100644 --- a/sdk/ruby/lib/clickhouse/loom/errors.rb +++ b/sdk/ruby/lib/clickhouse/loom/errors.rb @@ -13,8 +13,26 @@ module Loom # The code of an Error for a call that got no complete answer: the call may have run. CODE_NETWORK = "NETWORK" + # 5xx codes never resent, with their category (the TypeScript SDK's NEVER_RETRIED): + # a deployment's configuration, a model call that names no customer, and a write + # already committed whose rows are still on their way. + NEVER_RETRIED = { + "ANALYSIS_UNAVAILABLE" => "configuration", + "ASSISTANT_UNAVAILABLE" => "configuration", + "CODED_WIDTH_MISMATCH" => "configuration", + "GATEWAY_REQUIRED" => "configuration", + "MODEL_CALL_UNATTRIBUTED" => "internal", + "PUBLICATION_PENDING" => "dependency", + "TENANCY_REFUSED" => "configuration" + }.freeze + + # Codes the server answers before running the handler: resending runs the op once. + NEVER_RAN_CODES = %w[AUTH_UNAVAILABLE].freeze + # A non-2xx answer from the server, or a call that got no usable answer. - # Match on +code+, never on the message: the code is the contract. + # Match on +code+, never on the message: the code is the contract. An answer with a + # server code raises that code's subclass (PinnedConflict, RateLimited, ...: see + # generated/errors.rb), so a rescue can name the class instead. class Error < StandardError # The operation called, like "memory.get". attr_reader :op @@ -30,11 +48,13 @@ class Error < StandardError attr_reader :retry_after # The server's X-Request-Id; quote it in a bug report. attr_reader :request_id + # The server's whole detail object (like detail["pinned_blocker_id"]); {} when none. + attr_reader :detail alias retryable? retryable def initialize(message, op:, status: 0, code: "", category: "input", retryable: false, - retry_after: nil, request_id: "") + retry_after: nil, request_id: "", detail: {}) super(message) @op = op @status = status @@ -43,6 +63,7 @@ def initialize(message, op:, status: 0, code: "", category: "input", retryable: @retryable = retryable @retry_after = retry_after @request_id = request_id + @detail = detail end def to_s @@ -52,17 +73,23 @@ def to_s code.empty? ? "#{op}: HTTP #{status}: #{text}" : "#{op}: HTTP #{status} #{code}: #{text}" end - # The Error for a non-2xx answer. - def self.from_response(op, status, body, request_id, retry_after_header) + # The Error for a non-2xx answer: the subclass of its code, else Error. +idempotent+ + # false (an op the registry does not mark idempotent) makes a 5xx whose body names no + # +retryable+ not retryable, since the handler may have written before it failed. + def self.from_response(op, status, body, request_id, retry_after_header, idempotent: true) detail = extract_detail(body) - category, retryable = class_by_status(status) + code = detail["code"].to_s + category, retryable = default_class(code, status) category = detail["category"] if CATEGORIES.include?(detail["category"]) - retryable = detail["retryable"] if [true, false].include?(detail["retryable"]) + named = [true, false].include?(detail["retryable"]) + retryable = detail["retryable"] if named + retryable = false if !idempotent && !named && status >= 500 && !NEVER_RAN_CODES.include?(code) message = detail["message"].to_s message = "HTTP #{status}" if message.empty? - new(message, op: op, status: status, code: detail["code"].to_s, category: category, - retryable: retryable, retry_after: seconds(detail["retry_after_s"] || retry_after_header), - request_id: request_id.to_s) + klass = ERROR_CLASSES.fetch(code, Error) + klass.new(message, op: op, status: status, code: code, category: category, retryable: retryable, + retry_after: seconds(detail["retry_after_s"] || retry_after_header), + request_id: request_id.to_s, detail: detail) end # The Error for a call that never got an answer to read. @@ -92,9 +119,11 @@ def self.extract_detail(body) end private_class_method :extract_detail - # The server's own rule for an error whose body names no category, such as a - # proxy's page or an older server. - def self.class_by_status(status) + # The class of an error whose body names none, such as a proxy's page or an older + # server: a code never resent, else the server's own rule by HTTP status. + def self.default_class(code, status) + return [NEVER_RETRIED[code], false] if NEVER_RETRIED.key?(code) + case status when 401, 403 then ["auth", false] when 408, 429 then ["capacity", true] @@ -103,13 +132,13 @@ def self.class_by_status(status) else ["input", false] end end - private_class_method :class_by_status + private_class_method :default_class + # A Retry-After header (seconds or an HTTP-date) or detail.retry_after_s, in + # seconds; nil when absent, unreadable or not positive. def self.seconds(value) - wait = Float(value) - wait.positive? ? wait : nil - rescue ArgumentError, TypeError - nil + wait = RetryAfter.parse(value) + wait&.positive? ? wait : nil end private_class_method :seconds diff --git a/sdk/ruby/lib/clickhouse/loom/operations.rb b/sdk/ruby/lib/clickhouse/loom/operations.rb new file mode 100644 index 0000000000..dce91b3d84 --- /dev/null +++ b/sdk/ruby/lib/clickhouse/loom/operations.rb @@ -0,0 +1,58 @@ +# frozen_string_literal: true + +module ClickHouse + module Loom + # The declared spec of one served op (Generated::OPS holds one per op). +fields+ + # are the names its input accepts, +required+ the ones it cannot do without (the + # org, namespace and agent among them come from the client's identity). + OpSpec = Struct.new(:name, :group, :method_name, :idempotent, :read_only, :role, :maturity, + :fields, :required) do + # Whether a call gets an Idempotency-Key the server deduplicates on. + def deduplicated? + idempotent && !read_only + end + end + + # The ops of one group, as methods: client.memory is a MemoryOps. Each generated + # method takes the op's fields as keywords, an optional body Hash under them, and + # request_options: { idempotency_key:, retry_policy: }. + class OpGroup + REQUEST_OPTIONS = %i[idempotency_key retry_policy].freeze + + def initialize(client) + @client = client + end + + def inspect + "#<#{self.class.name}>" + end + + private + + # A nil keyword is left out of the body, so the server's default applies; send an + # explicit null in +body+. A keyword the op does not accept is an ArgumentError + # before anything is sent; a +body+ key is sent as it is. + def call_op(op, body, fields, request_options) + spec = Generated::OPS.fetch(op) + unknown = fields.keys.map(&:to_s) - spec.fields + raise ArgumentError, unknown_fields_message(spec, unknown) unless unknown.empty? + raise ArgumentError, "#{op}: body must be a Hash, got #{body.class}" unless body.nil? || body.is_a?(Hash) + + options = request_options || {} + bad = options.keys - REQUEST_OPTIONS + raise ArgumentError, "#{op}: unknown request_options #{bad.inspect} (known: #{REQUEST_OPTIONS.join(", ")})" if bad.any? + + input = (body || {}).transform_keys(&:to_s).merge(fields.compact.transform_keys(&:to_s)) + @client.call(op, input, **options) + end + + def unknown_fields_message(spec, unknown) + listed = unknown.map do |name| + near = DidYouMean::SpellChecker.new(dictionary: spec.fields).correct(name).first if defined?(DidYouMean) + near ? "#{name} (did you mean #{near}?)" : name + end + "#{spec.name} has no field #{listed.join(", ")}; it takes #{spec.fields.join(", ")}" + end + end + end +end diff --git a/sdk/ruby/lib/clickhouse/loom/retry_policy.rb b/sdk/ruby/lib/clickhouse/loom/retry_policy.rb new file mode 100644 index 0000000000..8ccee2a3e3 --- /dev/null +++ b/sdk/ruby/lib/clickhouse/loom/retry_policy.rb @@ -0,0 +1,109 @@ +# frozen_string_literal: true + +require "time" + +module ClickHouse + module Loom + # When a call is sent again, the same policy as the TypeScript and Python SDKs: + # + # - a connection that failed before the request went out is resent; + # - an HTTP status in +statuses+ (408 and 5xx) is resent for an op the registry + # marks idempotent, and for any other op only on a 408 or a refusal the server + # makes before running it (503 AUTH_UNAVAILABLE), since a 5xx after the handler + # started may follow a write; + # - a timeout or a response cut off after sending is resent only for an op whose + # Idempotency-Key the server deduplicates (idempotent and not read-only), unless + # +retry_timeouts+ says :never or :always; + # - a 429 is not a retry but pacing: the client waits out the server's Retry-After + # for at most the client's +rate_limit_max_wait+ seconds per call. + # + # A retried answer's Retry-After (or its detail.retry_after_s) replaces the backoff + # when it is at most +max_retry_after+ seconds. Every resend carries the same + # Idempotency-Key and X-Request-Id as the first attempt. + RetryPolicy = Struct.new(:max_attempts, :backoff, :backoff_max, :backoff_jitter, :statuses, + :retry_connection_errors, :retry_timeouts, :respect_retry_after, + :max_retry_after, :total_backoff_budget, keyword_init: true) do + # Total attempts including the first (1 disables retries); the first backoff in + # seconds, doubled per attempt up to +backoff_max+; +backoff_jitter+ 0..1 spreads + # each sleep over delay * (1 - jitter/2 + rand * jitter); +total_backoff_budget+ + # bounds the seconds one call may sleep between attempts. + def self.default + new(max_attempts: 3, backoff: 0.25, backoff_max: 5.0, backoff_jitter: 0.5, + statuses: [408, *500..599].freeze, retry_connection_errors: true, retry_timeouts: :idempotent, + respect_retry_after: true, max_retry_after: RetryAfter::MAX_SECONDS, + total_backoff_budget: Float::INFINITY).freeze + end + + # +base+ with the fields of +override+ (a Hash) set, each one checked. Raises + # ArgumentError naming the field and +source+. + def self.resolve(base, override, source = "Client") + return base if override.nil? || override.empty? + raise ArgumentError, "#{source}: retry_policy must be a Hash" unless override.is_a?(Hash) + + policy = base.dup + override.each { |name, value| policy[check_name(name, source)] = check(name.to_sym, value, source) } + policy.freeze + end + + def self.check_name(name, source) + return name.to_sym if members.include?(name.to_sym) + + raise ArgumentError, "#{source}: unknown retry_policy field #{name.inspect} (known: #{members.join(", ")})" + end + private_class_method :check_name + + def self.check(name, value, source) + case name + when :max_attempts + return value if value.is_a?(Integer) && value >= 1 + when :backoff_jitter + return value.to_f if value.is_a?(Numeric) && value.between?(0, 1) + when :backoff, :backoff_max, :max_retry_after, :total_backoff_budget + return value.to_f if value.is_a?(Numeric) && value >= 0 + when :statuses + list = Array(value) + return list.freeze if list.all? { |s| s.is_a?(Integer) && s.between?(100, 599) } + when :retry_timeouts + return value.to_sym if %w[never idempotent always].include?(value.to_s) + else # retry_connection_errors, respect_retry_after + return value if [true, false].include?(value) + end + raise ArgumentError, "#{source}: retry_policy #{name} cannot be #{value.inspect}" + end + private_class_method :check + + # Seconds to sleep before attempt +attempt+ + 1 (+attempt+ is the 1-based one that failed). + def backoff_delay(attempt, random = rand) + exponential = [backoff * (2**(attempt - 1)), backoff_max].min + exponential * (1 - (backoff_jitter / 2.0) + (random * backoff_jitter)) + end + end + + # Reads a Retry-After header: a number of seconds ("2", "0.5") or an HTTP-date. + module RetryAfter + # The longest wait believed; a 429 asking for longer is waited out for DEFAULT_SECONDS. + MAX_SECONDS = 60.0 + DEFAULT_SECONDS = 1.0 + + module_function + + # Seconds to wait from +now+, or nil when +value+ is absent or unreadable. A past + # date or a negative number is 0. + def parse(value, now = Time.now) + raw = value.to_s.strip + return nil if raw.empty? + return [Float(raw), 0.0].max if raw.match?(/\A[+-]?\d+(\.\d+)?\z/) + + [Time.httpdate(raw) - now, 0.0].max + rescue ArgumentError + nil + end + + # The bounded wait a 429 asks for. + def for_rate_limit(value, now = Time.now) + wait = parse(value, now) + wait.nil? || wait > MAX_SECONDS ? DEFAULT_SECONDS : wait + end + end + end +end diff --git a/sdk/ruby/test/configuration_test.rb b/sdk/ruby/test/configuration_test.rb new file mode 100644 index 0000000000..abb77adff9 --- /dev/null +++ b/sdk/ruby/test/configuration_test.rb @@ -0,0 +1,67 @@ +# frozen_string_literal: true + +require_relative "test_helper" + +class ConfigurationTest < LoomTest + def test_configure_sets_the_defaults_of_a_client_built_without_arguments + respond_json(200, { found: false }) + Loom.configure do |c| + c.base_url = @server.base_url + c.api_key = "configured-token" + c.org = "acme" + c.namespace = "support" + c.agent = "triage" + end + + Loom::Client.new.memory.get(memory_key: "k") + + assert_equal "Bearer configured-token", sent.headers["authorization"] + assert_equal({ "org" => "acme", "namespace" => "support", "agent" => "triage", "memory_key" => "k" }, sent_body) + end + + def test_an_argument_wins_over_configure_and_configure_over_the_environment + respond_json(200, { found: false }) + ENV["LOOM_BASE_URL"] = "http://127.0.0.1:1" + ENV["LOOM_API_KEY"] = "env-token" + Loom.configure do |c| + c.base_url = @server.base_url + c.api_key = "configured-token" + c.namespace = "support" + end + + c = Loom::Client.new(api_key: "arg-token", namespace: "user-42") + c.memory.get(memory_key: "k") + + assert_equal @server.base_url, c.base_url + assert_equal "Bearer arg-token", sent.headers["authorization"] + assert_equal "user-42", sent_body["namespace"] + end + + def test_configure_sets_the_retry_policy_and_a_client_argument_refines_it + Loom.configure { |c| c.retry_policy = { max_attempts: 5, backoff: 0.1 } } + + policy = Loom::Client.new(retry_policy: { backoff: 0.2 }).retry_policy + + assert_equal 5, policy.max_attempts + assert_in_delta 0.2, policy.backoff + end + + def test_a_bad_configured_policy_names_where_it_came_from + Loom.configure { |c| c.retry_policy = { retry_timeouts: :sometimes } } + + error = assert_raises(ArgumentError) { Loom::Client.new } + + assert_includes error.message, "ClickHouse::Loom.configure" + end + + def test_the_short_name_is_the_gem_module + assert_same ClickHouse::Loom, ::Loom + end + + def test_inspect_names_the_server_and_identity_but_never_the_token + text = client(api_key: "secret-token").inspect + + assert_includes text, "org=dev" + refute_includes text, "secret-token" + end +end diff --git a/sdk/ruby/test/errors_test.rb b/sdk/ruby/test/errors_test.rb index 62f6e2ebbf..f95fea8e90 100644 --- a/sdk/ruby/test/errors_test.rb +++ b/sdk/ruby/test/errors_test.rb @@ -125,6 +125,51 @@ def test_a_tls_server_whose_certificate_cannot_be_verified_is_a_network_error server&.close end + def test_a_server_code_raises_its_own_class_with_the_whole_detail + respond_json(409, { detail: { code: "PINNED_CONFLICT", message: "pinned", category: "input", retryable: false, + pinned_blocker_id: "m9" } }) + + error = assert_raises(Loom::PinnedConflict) { client.memory.set(memory_key: "k", value: "v") } + + assert_kind_of Loom::Error, error + assert_equal "PINNED_CONFLICT", error.code + assert_equal "m9", error.detail["pinned_blocker_id"] + end + + def test_a_rate_limit_raises_rate_limited + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow down" } }, { "Retry-After" => "4" }) + + error = assert_raises(Loom::RateLimited) { client.get("k") } + + assert_in_delta 4.0, error.retry_after + end + + def test_an_error_answer_that_does_not_echo_the_request_id_keeps_the_one_sent + respond_json(422, { detail: { code: "VALIDATION_FAILED", message: "bad" } }) + + error = assert_raises(Loom::ValidationFailed) { client.get("k") } + + assert_equal sent.headers["x-request-id"], error.request_id + refute_empty error.request_id + end + + def test_a_code_with_no_class_raises_error_itself + respond_json(418, { detail: { code: "BRAND_NEW_CODE", message: "teapot" } }) + + error = assert_raises(Loom::Error) { client.get("k") } + + assert_instance_of Loom::Error, error + assert_equal "BRAND_NEW_CODE", error.code + end + + def test_every_generated_error_class_names_its_code + assert_operator Loom::ERROR_CLASSES.size, :>=, 100 + Loom::ERROR_CLASSES.each do |code, klass| + assert_equal code, klass::CODE + assert_operator klass, :<, Loom::Error + end + end + private # A TLS listener with a self-signed certificate no client trusts. diff --git a/sdk/ruby/test/fake_server.rb b/sdk/ruby/test/fake_server.rb index 0eb6f24647..6b7f447a3e 100644 --- a/sdk/ruby/test/fake_server.rb +++ b/sdk/ruby/test/fake_server.rb @@ -20,9 +20,9 @@ def base_url "http://127.0.0.1:#{@server.addr[1]}" end - # Queues the answer to the next request. - def respond(status, body, headers = {}) - @responses << [status, body, headers] + # Queues the answer to the next request, written after +delay+ seconds. + def respond(status, body, headers = {}, delay: 0) + @responses << [status, body, headers, delay] end def close @@ -35,14 +35,18 @@ def close def serve loop do client = @server.accept - handle(client) + # One thread per connection, so a delayed answer does not hold up the next request. + Thread.new(client) { |c| handle(c) } end rescue IOError, Errno::EBADF nil end def handle(client) - method, path, = client.gets.split + request_line = client.gets + return if request_line.nil? # a client that connected and gave up + + method, path, = request_line.split headers = {} while (line = client.gets) && line != "\r\n" name, value = line.split(":", 2) @@ -50,7 +54,8 @@ def handle(client) end body = client.read(headers.fetch("content-length", "0").to_i).to_s @requests << Request.new(method, path, headers, body) - status, payload, extra = @responses.shift || [500, "no response queued", {}] + status, payload, extra, delay = @responses.shift || [500, "no response queued", {}, 0] + sleep(delay) if delay.positive? head = ["HTTP/1.1 #{status} Status", "Content-Length: #{payload.bytesize}", "Connection: close"] extra.each { |name, value| head << "#{name}: #{value}" } client.write("#{head.join("\r\n")}\r\n\r\n#{payload}") diff --git a/sdk/ruby/test/generated_test.rb b/sdk/ruby/test/generated_test.rb new file mode 100644 index 0000000000..2639bcecf6 --- /dev/null +++ b/sdk/ruby/test/generated_test.rb @@ -0,0 +1,140 @@ +# frozen_string_literal: true + +require_relative "test_helper" + +class GeneratedTest < LoomTest + UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/ + + def test_a_generated_method_posts_its_op_with_the_bound_identity_and_the_fields + respond_json(200, { memory_id: "m1", version: 1 }) + + out = client.memory.set(memory_key: "deploy_window", value: "Tue and Thu", tags: %w[ops]) + + assert_equal "/v1/memory.set", sent.path + assert_equal({ "org" => "dev", "namespace" => "local", "agent" => "assistant", "memory_key" => "deploy_window", + "value" => "Tue and Thu", "tags" => %w[ops] }, sent_body) + assert_equal({ "memory_id" => "m1", "version" => 1 }, out) + end + + def test_an_op_the_server_dedups_gets_an_idempotency_key_and_a_read_only_op_none + respond_json(200, {}) + respond_json(200, { found: false }) + + client.memory.set(memory_key: "k", value: "v") + set_key = @server.requests[0].headers["idempotency-key"] + client.memory.get(memory_key: "k") + + assert_match UUID, set_key + refute @server.requests[1].headers.key?("idempotency-key") + end + + def test_a_keyword_overrides_the_bound_identity_for_one_call + respond_json(200, {}) + respond_json(200, {}) + + c = client + c.memory.get(memory_key: "k", org: "acme", namespace: "user-42", agent: "support-bot") + c.memory.get(memory_key: "k") + + assert_equal({ "org" => "acme", "namespace" => "user-42", "agent" => "support-bot", "memory_key" => "k" }, + JSON.parse(@server.requests[0].body)) + assert_equal({ "org" => "dev", "namespace" => "local", "agent" => "assistant", "memory_key" => "k" }, + JSON.parse(@server.requests[1].body)) + end + + def test_a_nil_keyword_is_left_out_and_a_body_hash_can_send_an_explicit_null + respond_json(200, {}) + + client.memory.set({ "ttl_seconds" => nil, "value" => "from body" }, memory_key: "k", value: "v", tags: nil) + + assert_equal({ "org" => "dev", "namespace" => "local", "agent" => "assistant", "memory_key" => "k", + "value" => "v", "ttl_seconds" => nil }, sent_body) + end + + def test_a_keyword_the_op_does_not_take_is_refused_before_sending + error = assert_raises(ArgumentError) { client.memory.set(memory_key: "k", valeu: "v") } + + assert_includes error.message, "memory.set has no field valeu (did you mean value?)" + assert_empty @server.requests + end + + def test_request_options_carry_the_idempotency_key_and_refuse_unknown_ones + respond_json(200, {}) + + client.memory.set(memory_key: "k", value: "v", request_options: { idempotency_key: "job-7" }) + + assert_equal "job-7", sent.headers["idempotency-key"] + assert_raises(ArgumentError) { client.memory.get(memory_key: "k", request_options: { timeout: 1 }) } + end + + def test_a_field_named_like_an_option_stays_in_the_body + respond_json(200, {}) + + client.task.create(title: "t", idempotency_key: "task-key-1") + + assert_equal "task-key-1", sent_body["idempotency_key"] + refute_equal "task-key-1", sent.headers["idempotency-key"] + end + + def test_op_names_with_more_segments_and_shadowing_names_map_like_the_python_sdk + respond_json(200, {}) + respond_json(200, {}) + + client.tracker.source_add(name: "gh") + client.memory.inspect_(subject: "memory", id: "m1") + + assert_equal %w[/v1/tracker.source.add /v1/memory.inspect], @server.requests.map(&:path) + assert_equal "#", client.memory.inspect + end + + def test_search_with_no_argument_is_the_search_group + respond_json(200, { results: [] }) + + client.search.query(query: "deploys") + + assert_instance_of Loom::Generated::SearchOps, client.search + assert_equal "/v1/search.query", sent.path + end + + def test_an_op_the_table_does_not_know_is_sent_as_is_with_no_idempotency_key + respond_json(200, { ok: true }) + + out = client.call("future.op", { "x" => 1 }) + + assert_equal "/v1/future.op", sent.path + assert_equal 1, sent_body["x"] + refute sent.headers.key?("idempotency-key") + assert_equal({ "ok" => true }, out) + end + + def test_every_op_in_the_table_has_a_method_on_its_group_and_the_client_reaches_every_group + ops = Loom::Generated::OPS + c = client + + assert_equal Loom::Generated::OP_COUNT, ops.size + ops.each_value do |spec| + group = c.op_group(spec.group) + + assert_respond_to group, spec.method_name, spec.name + assert_same group, c.public_send(spec.group) unless spec.group == "search" + end + assert_equal ops.values.map(&:group).uniq.sort, Loom::Generated::GROUPS.keys + end + + def test_no_generated_name_shadows_a_method_every_object_has + taken = Object.public_instance_methods.map(&:to_s) + methods = Loom::Generated::OPS.values.map(&:method_name) + + assert_empty methods & taken + assert_empty Loom::Generated::GROUPS.keys & taken + end + + def test_the_spec_names_the_idempotency_and_the_fields_of_an_op + spec = Loom::Generated::OPS.fetch("memory.set") + + assert spec.deduplicated? + assert_includes spec.fields, "memory_key" + assert_includes spec.required, "value" + refute Loom::Generated::OPS.fetch("memory.get").deduplicated? + end +end diff --git a/sdk/ruby/test/retry_test.rb b/sdk/ruby/test/retry_test.rb new file mode 100644 index 0000000000..d8c3d02aae --- /dev/null +++ b/sdk/ruby/test/retry_test.rb @@ -0,0 +1,204 @@ +# frozen_string_literal: true + +require_relative "test_helper" + +class RetryTest < LoomTest + def setup + super + @sleeps = [] + end + + # Three attempts, no jitter, and sleeps recorded instead of slept. + def retrying(**options) + client(retry_policy: { max_attempts: 3, backoff_jitter: 0 }, rate_limit_max_wait: 15, + sleeper: ->(seconds) { @sleeps << seconds }, **options) + end + + def unavailable(code = "STORE_UNAVAILABLE", **detail) + { detail: { code: code, message: "busy", category: "dependency", retryable: true, **detail } } + end + + def test_an_idempotent_op_is_resent_after_a_5xx_with_exponential_backoff + respond_json(503, unavailable) + respond_json(502, unavailable) + respond_json(200, { found: false }) + + out = retrying.memory.get(memory_key: "k") + + assert_equal({ "found" => false }, out) + assert_equal 3, @server.requests.size + assert_equal [0.25, 0.5], @sleeps + assert_equal %w[0 1 2], @server.requests.map { |r| r.headers["x-loom-retry-count"] } + end + + def test_every_resend_repeats_the_idempotency_key_and_the_request_id + respond_json(500, { detail: { code: "INTERNAL_ERROR", message: "boom" } }) + respond_json(503, unavailable) + respond_json(200, { memory_id: "m1" }) + + retrying.memory.set(memory_key: "k", value: "v") + + keys = @server.requests.map { |r| r.headers["idempotency-key"] } + ids = @server.requests.map { |r| r.headers["x-request-id"] } + + assert_equal 3, keys.size + assert_equal 1, keys.uniq.size + refute_nil keys.first + assert_equal 1, ids.uniq.size + end + + def test_a_retry_after_header_replaces_the_backoff + respond_json(503, unavailable, { "Retry-After" => "2" }) + respond_json(200, {}) + + retrying.memory.get(memory_key: "k") + + assert_equal [2.0], @sleeps + end + + def test_the_body_retry_after_s_is_honoured_when_no_header_names_a_wait + respond_json(503, unavailable(retry_after_s: 1.5)) + respond_json(200, {}) + + retrying.memory.get(memory_key: "k") + + assert_equal [1.5], @sleeps + end + + def test_a_retry_after_longer_than_the_policy_believes_falls_back_to_the_backoff + respond_json(503, unavailable, { "Retry-After" => "600" }) + respond_json(200, {}) + + retrying.memory.get(memory_key: "k") + + assert_equal [0.25], @sleeps + end + + def test_the_last_answer_is_raised_once_the_attempts_are_spent + 3.times { respond_json(503, unavailable) } + + error = assert_raises(Loom::Error) { retrying.memory.get(memory_key: "k") } + + assert_equal "STORE_UNAVAILABLE", error.code + assert_equal 3, @server.requests.size + assert_equal 2, @sleeps.size + end + + def test_an_op_that_is_not_idempotent_is_not_resent_after_a_5xx_and_is_not_retryable + respond_json(500, { detail: { code: "INTERNAL_ERROR", message: "boom" } }) + + error = assert_raises(Loom::InternalError) { retrying.assistant.ask(question: "q") } + + assert_equal 1, @server.requests.size + refute error.retryable? + refute @server.requests.first.headers.key?("idempotency-key") + end + + def test_an_op_that_is_not_idempotent_is_resent_after_a_refusal_made_before_it_ran + respond_json(503, { detail: { code: "AUTH_UNAVAILABLE", message: "idp down" } }) + respond_json(200, { answer: "a" }) + + assert_equal({ "answer" => "a" }, retrying.assistant.ask(question: "q")) + assert_equal 2, @server.requests.size + end + + def test_a_configuration_error_and_a_never_retried_code_are_not_resent + respond_json(503, { detail: { code: "SCHEMA_PENDING", message: "migrate", category: "configuration", + retryable: false } }) + respond_json(503, { detail: { code: "PUBLICATION_PENDING", message: "committed" } }) + + assert_raises(Loom::SchemaPending) { retrying.memory.get(memory_key: "k") } + error = assert_raises(Loom::PublicationPending) { retrying.memory.get(memory_key: "k") } + + assert_equal 2, @server.requests.size + assert_equal "dependency", error.category + end + + def test_a_4xx_is_not_resent + respond_json(409, { detail: { code: "PINNED_CONFLICT", message: "pinned" } }) + + assert_raises(Loom::PinnedConflict) { retrying.memory.set(memory_key: "k", value: "v") } + assert_equal 1, @server.requests.size + end + + def test_a_429_is_waited_out_for_its_retry_after_and_not_counted_as_an_attempt + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "3" }) + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "3" }) + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "3" }) + respond_json(200, { memory_id: "m1" }) + + retrying(retry_policy: { max_attempts: 1 }).memory.set(memory_key: "k", value: "v") + + assert_equal [3.0, 3.0, 3.0], @sleeps + assert_equal 1, @server.requests.map { |r| r.headers["idempotency-key"] }.uniq.size + end + + def test_a_429_past_the_wait_budget_raises_rate_limited_with_its_wait + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "10" }) + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "10" }) + + error = assert_raises(Loom::RateLimited) { retrying.memory.get(memory_key: "k") } + + assert_equal [10.0], @sleeps + assert_in_delta 10.0, error.retry_after + assert error.retryable? + end + + def test_rate_limit_max_wait_zero_raises_the_first_429 + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "1" }) + + assert_raises(Loom::RateLimited) { retrying(rate_limit_max_wait: 0).memory.get(memory_key: "k") } + assert_empty @sleeps + end + + def test_a_refused_connection_is_resent_and_then_raised_as_a_network_error + sleeps = [] + c = Loom::Client.new(base_url: "http://127.0.0.1:1", open_timeout: 2, sleeper: ->(s) { sleeps << s }, + retry_policy: { max_attempts: 3, backoff_jitter: 0 }) + + error = assert_raises(Loom::Error) { c.memory.set(memory_key: "k", value: "v") } + + assert_equal Loom::CODE_NETWORK, error.code + assert_equal [0.25, 0.5], sleeps + end + + def test_a_timeout_is_resent_only_for_an_op_the_server_dedups + @server.respond(200, "{}", {}, delay: 0.6) + @server.respond(200, "{}", {}, delay: 0.6) + @server.respond(200, JSON.generate({ memory_id: "m1" })) + + get_error = assert_raises(Loom::Error) { retrying(read_timeout: 0.3).memory.get(memory_key: "k") } + out = retrying(read_timeout: 0.3).memory.set(memory_key: "k", value: "v") + + assert_equal Loom::CODE_NETWORK, get_error.code + assert_equal [0.25], @sleeps + assert_equal({ "memory_id" => "m1" }, out) + end + + def test_a_per_call_policy_overrides_the_client_one + respond_json(503, unavailable) + + assert_raises(Loom::Error) do + retrying.memory.get(memory_key: "k", request_options: { retry_policy: { max_attempts: 1 } }) + end + assert_equal 1, @server.requests.size + end + + def test_a_policy_field_is_checked_by_name + error = assert_raises(ArgumentError) { client(retry_policy: { max_attempts: 0 }) } + assert_includes error.message, "max_attempts" + + error = assert_raises(ArgumentError) { client(retry_policy: { attempts: 2 }) } + assert_includes error.message, "unknown retry_policy field :attempts" + end + + def test_retry_after_reads_seconds_and_http_dates + now = Time.utc(2026, 11, 22, 10, 0, 0) + + assert_in_delta 0.5, Loom::RetryAfter.parse("0.5", now) + assert_in_delta 30.0, Loom::RetryAfter.parse("Sun, 22 Nov 2026 10:00:30 GMT", now) + assert_in_delta 0.0, Loom::RetryAfter.parse("Sun, 22 Nov 2026 09:00:00 GMT", now) + assert_nil Loom::RetryAfter.parse("soon", now) + assert_in_delta 1.0, Loom::RetryAfter.for_rate_limit("3600", now) + end +end diff --git a/sdk/ruby/test/test_helper.rb b/sdk/ruby/test/test_helper.rb index fc4eca7321..7df066bb32 100644 --- a/sdk/ruby/test/test_helper.rb +++ b/sdk/ruby/test/test_helper.rb @@ -14,6 +14,7 @@ def setup @saved_env = ENV.to_h.slice("LOOM_BASE_URL", "LOOM_API_KEY") ENV.delete("LOOM_BASE_URL") ENV.delete("LOOM_API_KEY") + Loom.reset_configuration! end def teardown @@ -21,10 +22,15 @@ def teardown ENV.delete("LOOM_BASE_URL") ENV.delete("LOOM_API_KEY") @saved_env.each { |name, value| ENV[name] = value } + Loom.reset_configuration! end + # One attempt and no wait on a 429, so a test reads the first answer as it came; the + # retry tests pass their own policy. def client(**options) - Loom::Client.new(base_url: @server.base_url, org: "dev", namespace: "local", agent: "assistant", **options) + defaults = { base_url: @server.base_url, org: "dev", namespace: "local", agent: "assistant", + retry_policy: { max_attempts: 1 }, rate_limit_max_wait: 0 } + Loom::Client.new(**defaults, **options) end def respond_json(status, body, headers = {}) From 9fd878c6ba6da2e6b05e178752c6075c9713721b Mon Sep 17 00:00:00 2001 From: rahulsjha <132360698+rahulsjha@users.noreply.github.com> Date: Sun, 22 Nov 2026 08:49:24 +0530 Subject: [PATCH 3/4] Ruby SDK: pace a zero or past Retry-After on a 429 as 1 s A 429 whose Retry-After is 0 or a past date gave a zero wait, so the rate_limit_max_wait check always passed and the call resent forever. Such a wait is now 1 s (as an absent one is) and any positive wait is at least 0.1 s, so every paced resend spends part of rate_limit_max_wait and the call ends in Loom::RateLimited. Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com> --- sdk/ruby/README.md | 4 ++- sdk/ruby/lib/clickhouse/loom/client.rb | 4 +-- sdk/ruby/lib/clickhouse/loom/retry_policy.rb | 10 +++++-- sdk/ruby/test/retry_test.rb | 30 ++++++++++++++++++++ 4 files changed, 43 insertions(+), 5 deletions(-) diff --git a/sdk/ruby/README.md b/sdk/ruby/README.md index f3c315cd2b..14f0b31c31 100644 --- a/sdk/ruby/README.md +++ b/sdk/ruby/README.md @@ -111,7 +111,9 @@ The retry and idempotency rules of the TypeScript and Python SDKs: - The server's `Retry-After` (seconds or an HTTP-date) or `detail.retry_after_s` replaces the backoff when it is at most `max_retry_after` (60) seconds. - A `429` is pacing, not a retry: the call waits out `Retry-After` for at most - `rate_limit_max_wait` seconds, then raises `Loom::RateLimited`. + `rate_limit_max_wait` seconds, then raises `Loom::RateLimited`. A missing, zero or past + `Retry-After` (or one over 60 s) is waited as 1 s, and a shorter one as at least 0.1 s, so + every resend spends some of that budget. | `retry_policy` field | Default | | ------------------------- | ----------------------------------------------------------- | diff --git a/sdk/ruby/lib/clickhouse/loom/client.rb b/sdk/ruby/lib/clickhouse/loom/client.rb index 0752c120e7..b31c240e78 100644 --- a/sdk/ruby/lib/clickhouse/loom/client.rb +++ b/sdk/ruby/lib/clickhouse/loom/client.rb @@ -213,8 +213,8 @@ def resend_after_answer?(response, error, spec, policy, state) pause_before_next(policy, state, RetryAfter.parse(response["Retry-After"] || error.detail["retry_after_s"])) end - # A 429 is pacing, not a retry: wait the Retry-After (1 s when absent or over 60 s) - # while the call's rate_limit_max_wait allows, and send again. + # A 429 is pacing, not a retry: wait the Retry-After (1 s when absent, zero, past or over + # 60 s; at least 0.1 s) while the call's rate_limit_max_wait allows, and send again. def wait_out_rate_limit(response, state) wait = RetryAfter.for_rate_limit(response["Retry-After"]) return false unless @rate_limit_max_wait.positive? && state[:paced] + wait <= @rate_limit_max_wait diff --git a/sdk/ruby/lib/clickhouse/loom/retry_policy.rb b/sdk/ruby/lib/clickhouse/loom/retry_policy.rb index 8ccee2a3e3..670b9fb2ca 100644 --- a/sdk/ruby/lib/clickhouse/loom/retry_policy.rb +++ b/sdk/ruby/lib/clickhouse/loom/retry_policy.rb @@ -84,6 +84,9 @@ module RetryAfter # The longest wait believed; a 429 asking for longer is waited out for DEFAULT_SECONDS. MAX_SECONDS = 60.0 DEFAULT_SECONDS = 1.0 + # The shortest wait a 429 is paced by. Every paced resend then spends at least this + # much of rate_limit_max_wait, so a call resends at most rate_limit_max_wait / MIN_SECONDS times. + MIN_SECONDS = 0.1 module_function @@ -99,10 +102,13 @@ def parse(value, now = Time.now) nil end - # The bounded wait a 429 asks for. + # The bounded wait a 429 asks for. No wait, an unreadable one, zero, a past date or one + # over MAX_SECONDS is DEFAULT_SECONDS; a positive wait under MIN_SECONDS is MIN_SECONDS. def for_rate_limit(value, now = Time.now) wait = parse(value, now) - wait.nil? || wait > MAX_SECONDS ? DEFAULT_SECONDS : wait + return DEFAULT_SECONDS if wait.nil? || wait <= 0 || wait > MAX_SECONDS + + [wait, MIN_SECONDS].max end end end diff --git a/sdk/ruby/test/retry_test.rb b/sdk/ruby/test/retry_test.rb index d8c3d02aae..e285add71e 100644 --- a/sdk/ruby/test/retry_test.rb +++ b/sdk/ruby/test/retry_test.rb @@ -151,6 +151,32 @@ def test_rate_limit_max_wait_zero_raises_the_first_429 assert_empty @sleeps end + def test_a_429_with_a_zero_retry_after_spends_the_wait_budget_and_raises + 6.times do + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "0" }) + end + + assert_raises(Loom::RateLimited) do + retrying(retry_policy: { max_attempts: 1 }, rate_limit_max_wait: 3).memory.get(memory_key: "k") + end + + assert_equal [1.0, 1.0, 1.0], @sleeps + assert_equal 4, @server.requests.size + end + + def test_a_zero_or_past_retry_after_under_a_tiny_wait_budget_raises_the_first_429 + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, { "Retry-After" => "0" }) + respond_json(429, { detail: { code: "RATE_LIMITED", message: "slow" } }, + { "Retry-After" => "Sun, 01 Nov 2026 00:00:00 GMT" }) + + tiny = retrying(retry_policy: { max_attempts: 1 }, rate_limit_max_wait: 0.001) + assert_raises(Loom::RateLimited) { tiny.memory.get(memory_key: "k") } + assert_raises(Loom::RateLimited) { tiny.memory.get(memory_key: "k") } + + assert_empty @sleeps + assert_equal 2, @server.requests.size + end + def test_a_refused_connection_is_resent_and_then_raised_as_a_network_error sleeps = [] c = Loom::Client.new(base_url: "http://127.0.0.1:1", open_timeout: 2, sleeper: ->(s) { sleeps << s }, @@ -200,5 +226,9 @@ def test_retry_after_reads_seconds_and_http_dates assert_in_delta 0.0, Loom::RetryAfter.parse("Sun, 22 Nov 2026 09:00:00 GMT", now) assert_nil Loom::RetryAfter.parse("soon", now) assert_in_delta 1.0, Loom::RetryAfter.for_rate_limit("3600", now) + assert_in_delta 1.0, Loom::RetryAfter.for_rate_limit("0", now) + assert_in_delta 1.0, Loom::RetryAfter.for_rate_limit("Sun, 22 Nov 2026 09:00:00 GMT", now) + assert_in_delta 0.1, Loom::RetryAfter.for_rate_limit("0.001", now) + assert_in_delta 0.5, Loom::RetryAfter.for_rate_limit("0.5", now) end end From c13d7361ba8e369a20038440050effee84e451f1 Mon Sep 17 00:00:00 2001 From: rahulsjha <132360698+rahulsjha@users.noreply.github.com> Date: Sun, 22 Nov 2026 10:48:31 +0530 Subject: [PATCH 4/4] Ruby SDK: regenerate the op table for lessons on code.grep and code.enclosing Signed-off-by: rahulsjha <132360698+rahulsjha@users.noreply.github.com> --- sdk/ruby/lib/clickhouse/loom/generated/ops.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/ruby/lib/clickhouse/loom/generated/ops.rb b/sdk/ruby/lib/clickhouse/loom/generated/ops.rb index 5e5590de44..20f4c49d6c 100644 --- a/sdk/ruby/lib/clickhouse/loom/generated/ops.rb +++ b/sdk/ruby/lib/clickhouse/loom/generated/ops.rb @@ -36,11 +36,11 @@ module Generated "code.coverage.unwatch" => OpSpec.new("code.coverage.unwatch", "code", "coverage_unwatch", true, false, "viewer", "stable", %w[org namespace agent user_id consumer commit inbox].freeze, %w[commit inbox].freeze), "code.coverage.watch" => OpSpec.new("code.coverage.watch", "code", "coverage_watch", true, false, "viewer", "stable", %w[org namespace agent user_id consumer commit inbox].freeze, %w[commit inbox].freeze), "code.coverage_claim" => OpSpec.new("code.coverage_claim", "code", "coverage_claim", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer symbol path setting limit].freeze, [].freeze), - "code.enclosing" => OpSpec.new("code.enclosing", "code", "enclosing", true, true, "viewer", "stable", %w[org namespace agent user_id consumer locations include_body token_budget neighbours neighbour_k].freeze, %w[locations].freeze), + "code.enclosing" => OpSpec.new("code.enclosing", "code", "enclosing", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces org namespace agent user_id consumer locations include_body token_budget neighbours neighbour_k].freeze, %w[locations].freeze), "code.examples" => OpSpec.new("code.examples", "code", "examples", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer name symbol_id top_k].freeze, [].freeze), "code.files" => OpSpec.new("code.files", "code", "files", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer glob stem path_prefix limit].freeze, [].freeze), "code.first_build" => OpSpec.new("code.first_build", "code", "first_build", true, true, "viewer", "experimental", %w[org namespace agent user_id consumer sha pr_number].freeze, [].freeze), - "code.grep" => OpSpec.new("code.grep", "code", "grep", true, true, "viewer", "stable", %w[org namespace agent user_id consumer pattern regex case_sensitive path_prefix cursor exclude_unit_ids mode limit path_globs exclude_globs langs namespaces neighbours neighbour_k deadline_ms].freeze, %w[pattern].freeze), + "code.grep" => OpSpec.new("code.grep", "code", "grep", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces org namespace agent user_id consumer pattern regex case_sensitive path_prefix cursor exclude_unit_ids mode limit path_globs exclude_globs langs namespaces neighbours neighbour_k deadline_ms].freeze, %w[pattern].freeze), "code.history" => OpSpec.new("code.history", "code", "history", true, true, "viewer", "stable", %w[org namespace agent user_id consumer name symbol_id path numbers limit reviews_per_pr].freeze, [].freeze), "code.impact" => OpSpec.new("code.impact", "code", "impact", true, true, "viewer", "stable", %w[include_lessons lesson_namespaces pr_files pr_diff pr_head_sha pr_base_sha org namespace agent user_id consumer name symbol_id depth files diff exclude_authors summary_only per_hop_limit offset pr_number].freeze, [].freeze), "code.index_errors" => OpSpec.new("code.index_errors", "code", "index_errors", true, true, "viewer", "stable", %w[org namespace agent user_id consumer limit].freeze, [].freeze),