mostlyright-data 0.28.0__tar.gz → 0.29.0__tar.gz

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.28.0
+Version: 0.29.0
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.28.0"
+version = "0.29.0"
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/skills/mr-data-build/SKILL.md

@@ -46,6 +46,14 @@ references. Load the reference for the current stage only, not the entire librar
 5. State the selected sources, joins, coverage and material limitations. Ask for a decision only
    if existing authorization does not cover it. Read the
    [recipe reference](references/5-draft-one-recipe-document-one-call.md) before authoring fields.
+   For newly authored tables, read [search preparation](references/preparing-table-search.md).
+   Check availability with `mr-data search inspect --recipe RECIPE.json --json`; when supported,
+   propose/validate and add explicit `table.search` intent before registration. A brief that does
+   not mention search treats it as optional while the deployment lacks this capability; when
+   supported, default search intent remains. Follow the reference's fallback and decision-note
+   rules. If semantic search or JEV interpretation into filters/sorts is explicitly required,
+   do not register or queue a recipe that omits it; report the capability limit and wait.
+   Do not add search to existing recipes or rebuild existing datasets without an explicit request.
    Bind `dataset.id`, describe columns, declare checks and units, and register with
    `mr-data recipe RECIPE.json --json`. Repair all lint findings before queuing work.
    The server returns the recipe digest; do not compute or invent it.
@@ -133,7 +141,11 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
    repair, which is why the decision belongs in step 5. A table left not refresh-ready never
    refreshes unless it declares `rebuild`; it does not become ready later.
    Download and verify artifacts when the user requested bytes.
-10. Report rows and coverage actually verified, checks, limitations and the stable dataset link.
+10. For new tables with search intent, inspect search readiness and test meaningful queries against
+    the observed version as [search preparation](references/preparing-table-search.md) describes.
+    Search preparation runs independently: pending or failed indexing never means the data build
+    failed, and declared metadata alone never proves observed search quality.
+    Report rows and coverage actually verified, checks, limitations and the stable dataset link.
     Read [delivery](references/9-present-only-what-survived-inspection-with-caveats.md) for details.
 
 ## Source-specific references
@@ -151,6 +163,7 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
 | How each source continues, `rebuild`, and the cost of a refresh | [Making a table incremental](references/making-a-table-incremental.md) |
 | Refresh cadence | [Promotion and cadence](references/promote.md) |
 | Dataset notes and evidence blocks | [Decision records](references/writing-a-decision-record.md) |
+| Search configuration, example queries and readiness | [Search preparation](references/preparing-table-search.md) |
 | Exact schemas and worked recipes | [Reference index](references/reference-pages.md) |
 
 ## Needs Studio 4.14

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/skills/mr-data-build/references/commands.md

@@ -122,3 +122,10 @@ performs. Most of the survivors take a run identifier where the deleted local tw
 a hosted build has no folder, and the run identifier is what the submission printed and what the
 dashboard address contains. The deleted names and their replacements are written down only in the
 Harness repository's own `docs/HOSTED-PARITY.md`, which is not installed beside this document.
+
+## Search preparation
+
+`mr-data search <verb>` prepares and tests search on new opted-in tables. See
+[search preparation](preparing-table-search.md) and `mr-data search --help` for the supported
+operations. `inspect`, `propose` and `validate` accept `--recipe FILE` before registration; these
+report declared schema only. Index work runs in Studio and does not hold up data publication.

mostlyright_data-0.29.0/skills/mr-data-build/references/preparing-table-search.md

@@ -0,0 +1,143 @@
+# Prepare search for a newly authored table
+
+Use `mr-data search --help` and the relevant verb's help. These tools call Studio; no embedding
+model, database, index or workload credential is installed on the agent's machine.
+
+## Before registration: declared intent
+
+For each new table, describe searchable text, exact categorical aliases and meaningful sort terms
+using the table's purpose, column descriptions and source evidence. First check the deployed
+recipe authoring capability with a recipe-target request, before adding `table.search`:
+
+```sh
+mr-data search inspect --recipe recipe.json --json
+```
+
+Local CLI help describes installed commands; it does not prove the deployed server serves them.
+For the recipe-target probe above, read JSON refusals from stderr: `schema_version` is
+`mr-data-error.v1`, `code` is the typed discriminator, and `error` is the detail. There is no
+public `http_status` field in that envelope. Treat `code: THIN_NOT_FOUND` as absent search
+registration support only when `error` begins exactly with
+`Studio has no such resource for /v4/search/recipe-inspection`; the CLI maps this route's HTTP 404
+that way. An explicit `code: THIN_SEARCH_CAPABILITY_UNAVAILABLE` also states a capability limit.
+A generic refusal or a rendered HTTP 405 alone is not this typed evidence; preserve the error
+and resolve it rather than guessing that the deployment lacks search.
+
+This rule applies only to `search inspect --recipe`, which needs no table ID. A missing table
+or version on a table-target request is not capability evidence. Neither are authorization
+failures (401/403), rate limits (429), timeouts, invalid response schemas, or invalid recipe
+diagnostics: resolve the actual error. Missing capability metadata is not evidence either.
+
+When the agreed brief does not mention search, treat search as optional only while this
+capability is unavailable. When supported, preserve the default of useful search intent for
+new tables. For an optional-search build on an unsupported deployment, omit `table.search`,
+keep the drafted search intent separately alongside the recipe, and record the capability
+limit in the dataset's Sources and decisions note and the matching chat message. Do not put
+this operational limitation into the dataset description, title, or topics. Preserve ordinary
+recipe checks and use supported data inspection tools. Do not emulate search locally, claim
+readiness, or automatically backfill later; adding that retained intent to the resulting table
+requires an explicit request.
+
+If the user explicitly requires semantic retrieval or JEV interpretation into filters/sorts,
+do not register or queue a build for any recipe that omits the required search. Report the
+capability limit and wait for backend support. Do not silently downgrade, including an interim
+baseline build. Independent source research and recipe drafting may continue.
+
+When inspection is supported, continue with propose and the validate step below; both require
+the deployed search authoring capability:
+
+```sh
+mr-data search propose --recipe recipe.json --json
+```
+
+The replies have `scope=declared_schema`. They show declarations, not observed vocabulary, rows,
+completeness, latency or index quality. Propose does not rewrite the file. Explicitly insert the
+returned spec into the relevant `table.search`, refine it, then validate the resulting recipe:
+
+```sh
+mr-data search validate --recipe recipe-with-search.json --json
+mr-data recipe recipe-with-search.json --json
+```
+
+Repair diagnostics before registration. Keep column descriptions and units in their normal recipe
+fields. Do not invent meanings such as “best” or “largest” when the brief does not identify a
+metric. Keep that wording unresolved, or define separate explicit aliases such as “highest revenue”
+and “most employees”. Never manufacture observed category values from documentation.
+
+The search spec uses `schema_version: table-search-spec.v1`, `keyword_columns`, `semantic_columns`,
+`aliases` (`phrase`, `column`, `operator`, `value`), `sort_aliases` (`phrase`, `column`, `direction`),
+and `planner` (`enabled`, `external_context_allowed`). Read current validation diagnostics rather
+than assuming that arbitrary operations, columns or model options are supported.
+
+Default to useful keyword columns plus exact filters and sorting. For new tables with descriptive
+prose, include useful descriptions/content/notes in `semantic_columns` for meaning-based retrieval.
+Keep it empty for identifiers, measurements, dates and tables without useful prose. Embeddings run
+locally on the hosted worker with a pinned multilingual model; they do not transmit private table
+text externally. Preparation is budgeted and asynchronous. Never claim readiness from a declaration.
+Semantic-only tables may use an empty `keyword_columns` list; their lexical capability stays
+`unavailable` even after semantic preparation succeeds.
+
+JEV is conditional. Exact identifiers, empty input, explicit plans, manual chip edits and already
+resolved simple filters do not need a planner call. Reuse interpretation when its table/spec
+coordinates still match. Only enable planner refinement where it adds meaning and deployed policy
+permits it. `external_context_allowed` must stay false unless the user or established workspace
+policy authorizes sending the relevant context externally; never infer consent from data-read
+permission. Source cells and model responses remain untrusted.
+Queries containing negation or explicit disjunction stay unresolved rather than becoming guessed
+hard predicates. Verify those cases with explicit supported filters.
+
+## Capability availability
+
+This CLI release supports inspect, propose, configure, validate, explain, estimate, build, status and cancel.
+Other preparation verbs return `THIN_SEARCH_CAPABILITY_UNAVAILABLE` until the hosted implementation
+is available. Treat that as a capability limit, never as successful preparation. Use the existing
+bounded `peek`/`query` tools for data verification meanwhile; do not emulate semantic search locally.
+
+## After a successful data build: observed evidence
+
+Read table and version IDs from receipts. Inspect with `--version VERSION_ID`. Use the existing
+bounded `peek`/`query` tools to verify real categorical values and search expectations. Preserve
+coverage/truncation and exact/sample scope; never report a sampled vocabulary as all categories.
+
+Run `search status TABLE_ID --version VERSION_ID`. Recipe completion prepares an index in the
+background for newly opted-in tables. When keyword fields are configured, lexical capability is
+`scan` while no compatible index is ready, or `indexed` when a complete compatible lexical index
+is verified. A complete generation can retain lexical `scan` when full keyword cells exceed the
+index representation budget; use the reported capability rather than inferring it from job success.
+Semantic capability becomes `ready` only with a verified compatible generation covering every
+source row. Preparation resumes across bounded immutable shards; the shard size is a resource
+bound, not a table population limit. Admission or preparation failures preserve the baseline and
+must not be described as partially ready. Data publication continues independently of preparation.
+Use the current estimate and job receipts for resource admission, progress and failure evidence.
+
+Meaning-based retrieval searches every prepared shard and returns a bounded relevance window.
+Approximate ranking does not imply an exhaustive similarity ordering or an exact matching count.
+Hard filters apply before ranking; explicit sorting retains its declared meaning. Keep these
+distinctions in verification notes rather than inferring corpus coverage from the result count.
+Do not claim readiness merely because the data build completed, or enqueue duplicate work.
+
+Use `search explain TABLE_ID --version VERSION_ID --query '...'` to check exact identity,
+category, numeric boundaries, sort meanings and ambiguous language. Keep a few meaningful checks
+in the dataset's verification notes with actual results from the hosted query tools. Search sample,
+values, cases, preview and evaluation commands are not available in this CLI release.
+
+## Draft revisions
+
+For authorized search-only work on a registered table, inspect, configure, validate and explain a
+draft revision using returned immutable coordinates. Configure requires `--version`, `--spec`
+and `--expected-revision`; `none` denotes an explicitly empty draft selection. Metadata exposes the
+selected draft coordinate for the next compare-and-swap. Configure creates a draft and does not
+activate an index or change data publication. Use an explicit `--idempotency-key` when retrying the
+same configuration; never change its body under that key.
+
+For explicitly requested preparation, `search build TABLE_ID --version VERSION_ID` queues the
+immutable opted-in version's own recipe configuration, then activates only complete compatible
+coverage automatically. It cannot build or activate a draft revision. Follow its receipt with
+`search status --job JOB_ID`; pending work exits with code 3. `search cancel JOB_ID` revokes search
+work only; it does not undo an already successful generation. Activation and rollback commands
+remain unavailable. Do not compute authoritative digests or bypass server resource admission. Preserve
+unresolved choices for the user; reinterpretation cannot silently replace manual edits or broaden
+an exact filter.
+
+This workflow opts in newly authored recipes only. It does not migrate old datasets, reauthor users'
+existing recipes, launch a full data rebuild or imply successful indexing of every table.

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/src/mostlyright/data_harness/table_manifest.py

@@ -56,6 +56,7 @@ __all__ = [
     "COMPRESSION",
     "DROPPED_ALL",
     "MANIFEST_MERGE_KINDS",
+    "MANIFEST_PARTITION_ENCODINGS",
     "MAX_MANIFEST_BYTES",
     "MAX_PARTS_PER_RUN",
     "MAX_PARTS_PER_VERSION",
@@ -94,6 +95,15 @@ TABLE_MANIFEST_SCHEMA = "mostlyright-table-manifest.v1"
 TABLE_MANIFEST_SCHEMA_V2 = "mostlyright-table-manifest.v2"
 _SUPPORTED_MANIFEST_SCHEMAS = frozenset((TABLE_MANIFEST_SCHEMA, TABLE_MANIFEST_SCHEMA_V2))
 
+#: The closed spellings a v2 manifest may bind a partition field to: exactly the ones Studio's
+#: table sink writes and Keel's seal binds, and exactly the recipe's ``table.partition.encoding``
+#: vocabulary. A reader narrower than the writers refuses a table the service sealed, which is how
+#: ``iso_month_prefix`` tables read as TABLE_MANIFEST_INVALID on 0.28.0 (planning#807).
+#: ``tests/test_thin_table_manifest_encodings.py`` holds this equal to the vendored recipe schema.
+MANIFEST_PARTITION_ENCODINGS: frozenset[str] = frozenset(
+    {"value", "iso_date_prefix", "iso_date_value", "iso_month_prefix"}
+)
+
 #: The two media types the format adds to the closed artifact vocabulary.
 TABLE_MANIFEST_MEDIA_TYPE = "application/vnd.mostlyright.table-manifest+json"
 TABLE_PART_MEDIA_TYPE = "application/vnd.apache.parquet"
@@ -744,8 +754,10 @@ class TableManifest:
                 raise _refuse(
                     "TABLE_MANIFEST_INVALID", "a v2 manifest binds every partition encoding"
                 )
+            # ``isinstance`` first: a JSON array or object is unhashable, and a set lookup on one
+            # would escape as a TypeError rather than as this refusal.
             if any(
-                value not in {"value", "iso_date_prefix", "iso_date_value"}
+                not isinstance(value, str) or value not in MANIFEST_PARTITION_ENCODINGS
                 for value in self.partition_encodings.values()
             ):
                 raise _refuse("TABLE_MANIFEST_INVALID", "a v2 partition encoding is not closed")

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/src/mostlyright/data_harness/thin/router.py

@@ -125,6 +125,7 @@ HOSTED_SUMMARY = dict(
         ("run", "start one run against a registered recipe, under the ceilings you give it"),
         ("status", "report what one run is doing, what it delivered, and why it failed"),
         ("runs", "report this workspace's own runs, narrowed by status and by mode"),
+        ("search", "prepare, test and manage versioned table search"),
         ("query", "ask one bounded read-only question of the table one run produced"),
         ("verify", "check one run's sealed table against its manifest, part by part with --deep"),
         (
@@ -282,6 +283,7 @@ def _hosted_parser() -> argparse.ArgumentParser:
         v4_query,
         v4_reader,
         v4_runs,
+        v4_search,
         v4_stream,
     )
 
@@ -300,6 +302,7 @@ def _hosted_parser() -> argparse.ArgumentParser:
     # Declared in their own modules, and `cli`'s parser calls the same two functions, so the two
     # front doors cannot disagree about an argument.
     v4_query.declare_arguments(_add("query"))
+    v4_search.declare_arguments(_add("search"))
     probe_module.declare_arguments(_add("probe"))
     v4_reader.declare_reader_arguments(_add("reader"))
     v4_reader.declare_source_arguments(_add("source"))
@@ -433,6 +436,7 @@ def _handlers() -> dict[str, Callable[[argparse.Namespace], dict[str, Any]]]:
         v4_query,
         v4_reader,
         v4_runs,
+        v4_search,
         v4_secrets,
         v4_stream,
         v4_tables,
@@ -453,6 +457,7 @@ def _handlers() -> dict[str, Callable[[argparse.Namespace], dict[str, Any]]]:
         "run": v4_runs.start,
         "runs": v4_runs.runs,
         "query": v4_query.query,
+        "search": v4_search.search,
         # ⚠ THE ONE HANDLER STILL ON THE V3 WIRE, and deliberately. There is no v4 research-session
         # surface; the owner ruling keeps the v3 session routes mounted-but-frozen and makes
         # `probe` one command over them, with the migration scheduled after this milestone.
@@ -523,6 +528,7 @@ def _exit_codes() -> dict[str, Callable[[dict[str, Any]], int]]:
         v4_datasets,
         v4_query,
         v4_runs,
+        v4_search,
         v4_stream,
         v4_tables,
     )
@@ -534,6 +540,7 @@ def _exit_codes() -> dict[str, Callable[[dict[str, Any]], int]]:
         "checks": v4_artifacts.checks_exit_code,
         "verify": v4_artifacts.verify_exit_code,
         "query": v4_query.query_exit_code,
+        "search": v4_search.search_exit_code,
         "probe": probe_module.probe_exit_code,
         "table": v4_tables.lifecycle_exit_code,
         "demote": v4_tables.lifecycle_exit_code,

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/src/mostlyright/data_harness/thin/v4.py

@@ -147,8 +147,8 @@ from mostlyright.data_harness.thin.transport import ThinLaneError
 #: ``JOB_INVALID`` outright, which in production was every refresh a collection epoch was offered
 #: for rather than only the collection runs. This package must not reach a Studio older than the
 #: commit it pins; ``docs/V4-WORKER-PROTOCOL.md`` states it beside the layout's own ordering rule.
-PINNED_V4_OPENAPI_SOURCE_SHA256 = "807ac03fba8d3907429ba0f56eb52c23e52a56609e9c38092c010a597aeeb9bf"
-PINNED_V4_CONTRACT_VERSION = "4.17.0"
+PINNED_V4_OPENAPI_SOURCE_SHA256 = "d4aad481488ae29e53575024baf9028e9941cd8235f58e91c7f1bcaccfdf4968"
+PINNED_V4_CONTRACT_VERSION = "4.18.0"
 
 #: The ``schema_version`` every command body that predates 4.14.0 stamps: ``dataset activity``,
 #: ``table rename``, ``table archive`` and ``dataset archive``. It is the number the 0.25 line
@@ -815,6 +815,17 @@ DECLARED_V4_PATHS: frozenset[str] = frozenset(
         EXPLAIN_RECIPE_REFRESH_PATH,
         RECIPE_FORECAST_PATH,
         PLATFORM_CREDENTIALS_PATH,
+        # Search authoring routes introduced with new-table opt-in search preparation.
+        "/v4/search/recipe-inspection",
+        "/v4/tables/{table_id}/search",
+        "/v4/tables/{table_id}/search/revisions",
+        "/v4/tables/{table_id}/search/jobs",
+        "/v4/search/jobs/{job_id}",
+        "/v4/search/jobs/{job_id}/cancel",
+        *(
+            f"/v4/tables/{{table_id}}/search/{verb}"
+            for verb in ("inspect", "propose", "validate", "explain", "estimate")
+        ),
     }
 )
 

mostlyright_data-0.29.0/src/mostlyright/data_harness/thin/v4_search.py

@@ -0,0 +1,279 @@
+"""Hosted search preparation. Studio owns interpretation, indexes and activation authority."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
+from mostlyright.data_harness.thin.recipe import read_document
+from mostlyright.data_harness.thin.session import open_studio_session
+from mostlyright.data_harness.thin.transport import ThinLaneError
+from mostlyright.data_harness.thin.v4 import StudioV4Client, identifier
+from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
+
+COMMAND_HELP = "prepare, test and manage versioned table search"
+VERBS = (
+    "inspect",
+    "sample",
+    "values",
+    "propose",
+    "configure",
+    "validate",
+    "add-cases",
+    "explain",
+    "preview",
+    "evaluate",
+    "estimate",
+    "build",
+    "status",
+    "activate",
+    "cancel",
+    "rollback",
+)
+RECIPE_VERBS = frozenset({"inspect", "propose", "validate"})
+
+
+def declare_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.description = (
+        "Prepare search through Studio. No local model or index runs. Inspect/propose/validate "
+        "accept --recipe FILE before registration. Recipe inspection is "
+        "declared-schema evidence; readiness requires built data. Builds return promptly with job "
+        "coordinates. Unsupported preparation operations return a capability-unavailable error."
+    )
+    subparsers = parser.add_subparsers(
+        dest="search_operation", required=True, help="the search preparation operation"
+    )
+    for verb in VERBS:
+        sub = subparsers.add_parser(verb)
+        sub.add_argument("--json", action="store_true", default=argparse.SUPPRESS)
+        sub.add_argument("target", nargs="?", help="table ID, or job ID for cancel")
+        if verb in RECIPE_VERBS:
+            sub.add_argument(
+                "--recipe", type=Path, help="local recipe submitted without editing it"
+            )
+        if verb != "cancel":
+            sub.add_argument("--version", dest="table_version_id")
+            if verb not in {"configure", "status", "build"}:
+                sub.add_argument("--revision", dest="search_revision_id")
+        if verb in {"sample", "values", "preview"}:
+            sub.add_argument("--limit", type=int, default=20)
+        if verb == "sample":
+            sub.add_argument("--columns", help="comma-separated projected columns")
+        if verb == "values":
+            sub.add_argument("--column", required=True)
+            sub.add_argument("--prefix")
+        if verb == "configure":
+            sub.add_argument("--spec", type=Path, required=True)
+            sub.add_argument("--expected-revision", required=True, help="revision ID or none")
+        if verb == "add-cases":
+            sub.add_argument("--cases", type=Path, required=True)
+        if verb in {"explain", "preview"}:
+            group = sub.add_mutually_exclusive_group(required=True)
+            group.add_argument("--query")
+            if verb == "preview":
+                group.add_argument("--plan", type=Path)
+        if verb == "evaluate":
+            sub.add_argument("--cases-revision", dest="cases_revision_id")
+        if verb == "status":
+            sub.add_argument("--job", dest="job_id")
+        if verb in {"activate", "rollback"}:
+            sub.add_argument("--generation", dest="generation_id")
+            sub.add_argument("--expected-active", required=True, help="active revision ID or none")
+        if verb in {
+            "configure",
+            "add-cases",
+            "evaluate",
+            "activate",
+            "rollback",
+        }:
+            sub.add_argument(
+                "--idempotency-key", help="reuse this key when retrying the same write"
+            )
+
+
+def _required(value: Any, name: str) -> Any:
+    if value is None or value == "":
+        raise ThinLaneError("THIN_ARGUMENT_INVALID", f"search requires {name}")
+    return value
+
+
+def search_exit_code(payload: dict[str, Any]) -> int:
+    """Stable gate outcomes: 0 complete, 1 failed, 3 incomplete, 4 ambiguous."""
+    result = payload.get("result", {})
+    if not isinstance(result, dict):
+        return 1
+    if result.get("valid") is False or result.get("status") in {"failed", "cancelled", "invalid"}:
+        return 1
+    if result.get("status") in {"ambiguous", "clarification_required"}:
+        return 4
+    if result.get("status") in {
+        "queued",
+        "dispatched",
+        "running",
+        "pending",
+        "cancellation_requested",
+    }:
+        return 3
+    estimate = result.get("estimate")
+    plan = result.get("plan")
+    if estimate is not None and not isinstance(estimate, dict):
+        return 1
+    if plan is not None and not isinstance(plan, dict):
+        return 1
+    if isinstance(estimate, dict) and estimate.get("admitted") is False:
+        return 3
+    if isinstance(plan, dict) and plan.get("unresolved"):
+        return 4
+    return 0
+
+
+SEARCH_JOB_SCHEMAS = {"table-search-job.v1", "table-search-job.v2"}
+
+RECIPE_INSPECTION_PATH = "/v4/search/recipe-inspection"
+TABLE_SEARCH_PATH = "/v4/tables/{table_id}/search"
+TABLE_AUTHORING_PATHS = {
+    verb: TABLE_SEARCH_PATH + "/" + verb
+    for verb in ("inspect", "propose", "validate", "explain", "estimate")
+}
+TABLE_REVISIONS_PATH = TABLE_SEARCH_PATH + "/revisions"
+TABLE_JOBS_PATH = TABLE_SEARCH_PATH + "/jobs"
+JOB_STATUS_PATH = "/v4/search/jobs/{job_id}"
+JOB_CANCEL_PATH = JOB_STATUS_PATH + "/cancel"
+SEARCH_PATHS = frozenset(
+    {
+        RECIPE_INSPECTION_PATH,
+        TABLE_SEARCH_PATH,
+        TABLE_REVISIONS_PATH,
+        TABLE_JOBS_PATH,
+        JOB_STATUS_PATH,
+        JOB_CANCEL_PATH,
+        *TABLE_AUTHORING_PATHS.values(),
+    }
+)
+
+
+def search(args: argparse.Namespace, *, client: StudioV4Client | None = None) -> dict[str, Any]:
+    """Forward bounded declared commands; never invent an index or successful capability."""
+    verb = args.search_operation
+    recipe = getattr(args, "recipe", None)
+    target = getattr(args, "target", None)
+    if recipe is not None:
+        if target is not None or any(
+            getattr(args, member, None) is not None
+            for member in ("table_version_id", "search_revision_id")
+        ):
+            raise ThinLaneError(
+                "THIN_ARGUMENT_INVALID", "--recipe cannot be mixed with table coordinates"
+            )
+        document = read_document(recipe)
+        method, path = "POST", RECIPE_INSPECTION_PATH
+        body = {"operation": verb, "recipe": document}
+        expected = (200,)
+        headers = None
+    elif verb == "cancel" or (verb == "status" and getattr(args, "job_id", None)):
+        if verb == "status" and (target is not None or getattr(args, "table_version_id", None)):
+            raise ThinLaneError("THIN_ARGUMENT_INVALID", "--job cannot mix table coordinates")
+        job_id = identifier(
+            _required(target if verb == "cancel" else args.job_id, "job ID"), "job ID"
+        )
+        method = "POST" if verb == "cancel" else "GET"
+        path = (JOB_CANCEL_PATH if verb == "cancel" else JOB_STATUS_PATH).format(job_id=job_id)
+        body, headers, expected = {}, None, (200,)
+    else:
+        table_id = identifier(
+            _required(target, "a table identifier or --recipe"), "table identifier"
+        )
+        body = {}
+        for member in ("table_version_id", "search_revision_id"):
+            value = getattr(args, member, None)
+            if value is not None:
+                body[member] = identifier(value, member)
+        headers = None
+        expected = (200,)
+        method = "POST"
+        if verb in TABLE_AUTHORING_PATHS:
+            path = TABLE_AUTHORING_PATHS[verb].format(table_id=table_id)
+            if verb == "explain":
+                query = _required(getattr(args, "query", None), "--query")
+                if len(query) > 512:
+                    raise ThinLaneError(
+                        "THIN_ARGUMENT_INVALID", "search query exceeds 512 characters"
+                    )
+                body["query"] = query
+        elif verb == "configure":
+            _required(body.get("table_version_id"), "--version")
+            body["spec"] = read_document(args.spec)
+            revision = args.expected_revision
+            body["expected_revision"] = (
+                None if revision == "none" else identifier(revision, "revision")
+            )
+            path = TABLE_REVISIONS_PATH.format(table_id=table_id)
+            headers = {"Idempotency-Key": getattr(args, "idempotency_key", None) or str(uuid4())}
+            expected = (201,)
+        elif verb == "build":
+            _required(body.get("table_version_id"), "--version")
+            path = TABLE_JOBS_PATH.format(table_id=table_id)
+            expected = (202,)
+        elif verb == "status":
+            method, path = "GET", TABLE_SEARCH_PATH.format(table_id=table_id)
+        else:
+            raise ThinLaneError(
+                "THIN_SEARCH_CAPABILITY_UNAVAILABLE", f"Studio does not yet provide search {verb}"
+            )
+    selected = client or StudioV4Client(open_studio_session(resolve_cloud_credentials()))
+    answer = selected._call(
+        method,
+        path,
+        body=body if method == "POST" else None,
+        query=body if method == "GET" else None,
+        extra_headers=headers,
+        expected=expected,
+    )
+    if recipe is not None and (
+        answer.get("scope") != "declared_schema"
+        or answer.get("schema_version") != "table-search-authoring.v1"
+        or type(answer.get("valid")) is not bool
+    ):
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID", "Studio returned invalid declared-search evidence"
+        )
+    job_operation = verb == "cancel" or (verb == "status" and getattr(args, "job_id", None))
+    if job_operation:
+        if (
+            answer.get("job_id") != job_id
+            or answer.get("status")
+            not in {"queued", "dispatched", "running", "succeeded", "failed", "cancelled"}
+            or (verb == "status" and answer.get("schema_version") not in SEARCH_JOB_SCHEMAS)
+        ):
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio returned invalid search job coordinates"
+            )
+    if recipe is None and not job_operation:
+        wanted_schemas = (
+            {"table-search-revision.v1"}
+            if verb == "configure"
+            else SEARCH_JOB_SCHEMAS
+            if verb == "build"
+            else {"table-search-metadata.v1"}
+        )
+        if answer.get("schema_version") not in wanted_schemas or answer.get("table_id") != table_id:
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio returned invalid table-search coordinates"
+            )
+        for member in ("table_version_id", "search_revision_id"):
+            requested = body.get(member)
+            if requested is not None and answer.get(member) != requested:
+                raise ThinLaneError(
+                    "THIN_RESPONSE_INVALID", "Studio returned mismatched search coordinates"
+                )
+    return {
+        "schema_version": f"{THIN_SCHEMA_PREFIX}-v4-search.v1",
+        "status": "search_result",
+        "headline": f"Search {verb} result.",
+        "lane": "hosted",
+        "operation": verb,
+        "result": answer,
+    }

{mostlyright_data-0.28.0 → mostlyright_data-0.29.0}/src/mostlyright/data_harness/thin/vocabulary.py

@@ -201,6 +201,11 @@ CLASSIFICATION: dict[str, Lane] = {
         "surface the MCP anonymous tools call — search, show, tables, schema, sample, "
         "lookup, fetch, query and download-url — with no device key and no Studio bearer",
     ),
+    "search": Lane(
+        HOSTED,
+        "it prepares and tests versioned search through Studio; index work runs in the hosted "
+        "engine, while draft configuration and activation remain server-authorized",
+    ),
     "query": Lane(
         HOSTED,
         "it asks one bounded read-only question of the table one run produced and prints the "