maxc-cli 0.9.0__tar.gz → 0.9.3__tar.gz

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maxc-cli
-Version: 0.9.0
+Version: 0.9.3
 Summary: Agent-native MaxCompute CLI for external coding agents
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.9.0"
+__version__ = "0.9.3"

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/app.py

@@ -76,9 +76,9 @@ from .utils import (
     decode_cursor,
     encode_cursor,
     enforce_read_only_sql,
-    known_write_operations,
     now_utc_iso,
     sql_has_limit,
+    sql_requires_authorization,
     validate_csv_delimiter,
     validate_download_output_path,
     validate_upload_input_path,
@@ -772,11 +772,10 @@ class MaxCApp:
                         "the existing job using its persisted execution context."
                     ),
                 )
-        write_operations = known_write_operations(sql)
-        if write_operations and ((retry_on or []) or max_retries):
+        requires_authorization = sql_requires_authorization(sql)
+        if requires_authorization and ((retry_on or []) or max_retries):
             raise ValidationError(
-                "Automatic retries are not supported for mutating SQL "
-                f"({', '.join(write_operations)}).",
+                "Automatic retries are not supported for mutating SQL or SQL not proven read-only.",
                 suggestion=(
                     "Remove --retry-on and --max-retries. Inspect the original "
                     "job/result before deciding whether a manual retry is safe."
@@ -6939,16 +6938,10 @@ class MaxCApp:
         force: 'bool' = False,
         execution_settings: '_McqaExecutionSettings | None' = None,
     ) -> 'QueryResult':
-        if sql.startswith("@natural"):
-            raise FeatureUnavailableError(
-                "`@natural` is a roadmap feature and is not available in the current MVP.",
-                suggestion="Use `maxc meta search` or `maxc meta describe` to inspect tables, then submit plain SQL.",
-            )
-        write_operations = known_write_operations(sql)
-        if write_operations and (retry_on or max_retries):
+        requires_authorization = sql_requires_authorization(sql)
+        if requires_authorization and (retry_on or max_retries):
             raise ValidationError(
-                "Automatic retries are not supported for mutating SQL "
-                f"({', '.join(write_operations)}).",
+                "Automatic retries are not supported for mutating SQL or SQL not proven read-only.",
                 suggestion="Remove retry flags and verify the first execution before retrying manually.",
             )
 
@@ -7018,11 +7011,6 @@ class MaxCApp:
         explain: 'bool',
         force: 'bool' = False,
     ) -> 'dict[str, Any]':
-        if sql.startswith("@natural"):
-            raise FeatureUnavailableError(
-                "`@natural` is a roadmap feature and is not available in the current MVP.",
-                suggestion="Use `maxc meta search` or `maxc meta describe` to inspect tables, then submit plain SQL.",
-            )
         if explain:
             return self.backend.explain_query(sql, project=project, force=force)
         return self.backend.estimate_query_cost(sql, project=project, force=force)
@@ -7125,16 +7113,16 @@ class MaxCApp:
 
         # Build actions
         qe_actions: list[SuggestedAction] = []
-        write_operations = known_write_operations(result.sql_executed)
+        requires_authorization = sql_requires_authorization(result.sql_executed)
         if result.tables_used and result.extra_metadata.get("result_kind") != "statement":
             qe_actions.append(action("meta.describe", data=data, metadata=metadata))
         if result.has_more and next_cursor:
             qe_actions.append(action("query.paginate", data=data, metadata=metadata))
         elif result.has_more and result.job_id:
             qe_actions.append(action("job.result", data=data, metadata=metadata))
-        if dry_run and not write_operations:
+        if dry_run and not requires_authorization:
             qe_actions.append(action("job.submit", data=data, metadata=metadata))
-        elif dry_run and write_operations:
+        elif dry_run and requires_authorization:
             warnings.append(
                 "No replay action was generated for mutating SQL. A dry-run does not "
                 "authorize later execution; rerun the exact statement with `--force` "
@@ -7187,8 +7175,8 @@ class MaxCApp:
 
         # Build actions
         ae_actions: list[SuggestedAction] = []
-        write_operations = known_write_operations(sql)
-        if not write_operations:
+        requires_authorization = sql_requires_authorization(sql)
+        if not requires_authorization:
             if command == "query.cost":
                 ae_actions.append(action("query.explain", data=analysis, metadata=metadata))
             ae_actions.append(action("query", data=analysis, metadata=metadata))

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/backend/odps.py

@@ -13,7 +13,7 @@ from ..helpers import (
     translate_odps_error,
 )
 from ..models import QueryResult
-from ..utils import extract_table_names
+from ..utils import detect_operation, extract_table_names
 from .auth import AuthMixin
 from .catalog import CatalogMixin
 from .data import DataMixin
@@ -124,9 +124,22 @@ class OdpsBackend(
         """Convert ODPS instance to QueryResult."""
         fallback_warnings: list[str] = []
         statement_operation = _write_operation(sql)
-        resultless_statement = statement_operation is not None or (
-            not sql.strip() and getattr(instance, "_is_select", None) is False
-        )
+        instance_is_select = getattr(instance, "_is_select", None)
+        confirmed_task_results = None
+        resultless_statement = statement_operation is not None and instance_is_select is not True
+        if not resultless_statement and instance_is_select is False:
+            try:
+                task_results = instance.get_task_results()
+            except Exception:
+                # A result retrieval failure cannot prove an unknown statement
+                # has no output. Keep its reader/error path and original job.
+                pass
+            else:
+                if isinstance(task_results, dict):
+                    confirmed_task_results = task_results
+                    resultless_statement = not any(str(value or "").strip() for value in task_results.values())
+                    if resultless_statement and sql.strip():
+                        statement_operation = detect_operation(sql)
         if resultless_statement:
             # Successful write statements have no tabular result. In
             # particular, PyODPS's DDL fallback reader may try to iterate a
@@ -198,7 +211,11 @@ class OdpsBackend(
                         # PyODPS's CSV reader raise IndexError while casting
                         # fields. The job itself succeeded, so degrade to the
                         # raw task-result text instead of failing the query.
-                        task_results = self._safe_task_results(instance)
+                        task_results = (
+                            confirmed_task_results
+                            if confirmed_task_results is not None
+                            else self._safe_task_results(instance)
+                        )
                         if not any(str(value).strip() for value in task_results.values()):
                             # No raw text to degrade to — surface the real error.
                             raise

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/backend/query.py

@@ -117,9 +117,8 @@ def _parse_sql_with_hints(
         )
 
     # Validate both the executable statement and the leading SET execution
-    # context. The public path is a positive allowlist: unknown dialect
-    # extensions and unreviewed mutation hints are blocked before the service
-    # sees them rather than falling through a mutation denylist.
+    # context. Reads are recognized locally; any other exact statement needs
+    # explicit authorization before MaxCompute validates its syntax and permissions.
     enforce_read_only_sql(sql, force=force)
 
     # Multi-statement SQL needs script mode for MaxCompute to accept it.
@@ -183,6 +182,47 @@ def _pop_priority(hints: 'dict[str, str]') -> 'int | None':
         ) from None
 
 
+def _invoke_sql_with_hints(
+    method, sql: 'str', *, hints: 'dict[str, str]', schema_aware: 'bool' = False, **kwargs,
+):
+    # PyODPS run_sql resolves self.schema without statement hints, then can
+    # overwrite an explicit two-tier hint with the tenant's three-tier default.
+    # Keep statement settings scoped while the original hints build each task.
+    namespace = next(
+        (value for key, value in hints.items() if key.lower() == "odps.namespace.schema"),
+        None,
+    )
+    namespace = namespace.strip().lower() if namespace is not None else None
+    if namespace not in {"false", "true"}:
+        return method(sql, hints=hints, **kwargs)
+
+    implicit_namespace = namespace
+    if namespace == "true":
+        default_schema = next(
+            (value for key, value in hints.items() if key.lower() == "odps.default.schema"),
+            None,
+        )
+        if default_schema and schema_aware:
+            # run_sql otherwise replaces the explicit schema hint with self.schema.
+            # Cost tasks and MCQA v1 accept the original hints, not this SDK kwarg.
+            kwargs["default_schema"] = default_schema
+        elif default_schema:
+            # MCQA v1 cannot accept default_schema, including before its offline
+            # fallback. Suppress self.schema's implicit default only in this
+            # context; the original true/schema hints still build every task.
+            implicit_namespace = "false"
+
+    from odps.config import option_context
+
+    with option_context() as options:
+        options.sql.settings = {
+            **(options.sql.settings or {}),
+            **hints,
+            "odps.namespace.schema": implicit_namespace,
+        }
+        return method(sql, hints=hints, **kwargs)
+
+
 class QueryMixin:
     """Mixin providing query execution methods."""
 
@@ -202,10 +242,9 @@ class QueryMixin:
 
         Parses any leading ``SET key=value;`` statements from the SQL
         and passes them as execution hints to the MaxCompute backend.
-        Recognized data-plane write operations (INSERT, CREATE TABLE, DROP
-        TABLE, etc.) are blocked client-side unless *force* is True. Unknown,
-        procedural, permission, session-control, and administrative SQL remain
-        blocked even when *force* is True.
+        Statements not proven read-only require explicit authorization and
+        *force*. Approved operation names and SET keys are passed to MaxCompute
+        for syntax validation and permission checks.
 
         Args:
             sql: SQL query, optionally prefixed with SET statements.
@@ -215,7 +254,7 @@ class QueryMixin:
                 ``client.execute_sql_cost()``).
             offset: Row offset for cursor-based pagination.
             timeout: Timeout in seconds (default: 300s / 5 minutes).
-            force: If True, allow one recognized data-plane DDL/DML statement.
+            force: If True, allow one explicitly authorized non-read statement.
 
         Raises:
             ValidationError: If SET syntax is invalid.
@@ -229,7 +268,8 @@ class QueryMixin:
 
         if dry_run:
             try:
-                sql_cost = self.client.execute_sql_cost(
+                sql_cost = _invoke_sql_with_hints(
+                    self.client.execute_sql_cost,
                     actual_sql, project=project, hints=hints,
                 )
             except Exception as exc:
@@ -270,13 +310,16 @@ class QueryMixin:
                     interactive_kwargs["project"] = project
                     interactive_kwargs["use_mcqa_v2"] = True
                     interactive_kwargs["quota_name"] = getattr(execution_settings, "quota_name", None)
-                instance = self.client.execute_sql_interactive(
+                instance = _invoke_sql_with_hints(
+                    self.client.execute_sql_interactive,
                     actual_sql,
+                    schema_aware=getattr(execution_settings, "version", "v2") == "v2",
                     **interactive_kwargs,
                 )
             else:
-                instance = self.client.run_sql(
-                    actual_sql, project=project, hints=hints, **priority_kwargs,
+                instance = _invoke_sql_with_hints(
+                    self.client.run_sql,
+                    actual_sql, project=project, hints=hints, schema_aware=True, **priority_kwargs,
                 )
         except Exception as exc:
             raise translate_odps_error(exc) from exc
@@ -334,7 +377,8 @@ class QueryMixin:
         actual_sql, hints, _priority = _parse_sql_with_hints(sql, force=force)
         started_monotonic = monotonic()
         try:
-            sql_cost = self.client.execute_sql_cost(
+            sql_cost = _invoke_sql_with_hints(
+                self.client.execute_sql_cost,
                 actual_sql, project=project, hints=hints,
             )
         except Exception as exc:
@@ -343,7 +387,9 @@ class QueryMixin:
             **build_query_outline(actual_sql),
             "project": project,
             "cost_model": "maxcompute_native_sql_cost",
-            "estimated_input_size_bytes": int(sql_cost.input_size or 0),
+            "estimated_input_size_bytes": (
+                int(sql_cost.input_size) if sql_cost.input_size is not None else None
+            ),
             "task_cost_cpu": None,
             "task_cost_memory": None,
             "sql_complexity": sql_cost.complexity,
@@ -378,10 +424,12 @@ class QueryMixin:
         plan_text: str | None = None
         plan_warning: str | None = None
         try:
-            instance = self.client.execute_sql(
+            instance = _invoke_sql_with_hints(
+                self.client.execute_sql,
                 f"EXPLAIN {actual_sql}",
                 project=project,
                 hints=explain_hints,
+                schema_aware=True,
                 **priority_kwargs,
             )
             try:
@@ -397,7 +445,8 @@ class QueryMixin:
 
         # Cost estimate alongside the plan
         try:
-            sql_cost = self.client.execute_sql_cost(
+            sql_cost = _invoke_sql_with_hints(
+                self.client.execute_sql_cost,
                 actual_sql, project=project, hints=hints,
             )
         except Exception:
@@ -448,7 +497,7 @@ class QueryMixin:
             sql: SQL query, optionally prefixed with SET statements.
             project: ODPS project name.
             idempotency_key: Optional unique ID for deduplication.
-            force: If True, allow one recognized data-plane DDL/DML statement
+            force: If True, allow one explicitly authorized non-read statement
                 after explicit authorization.
 
         Returns:
@@ -471,15 +520,19 @@ class QueryMixin:
                     interactive_kwargs["project"] = project
                     interactive_kwargs["use_mcqa_v2"] = True
                     interactive_kwargs["quota_name"] = getattr(execution_settings, "quota_name", None)
-                instance = self.client.run_sql_interactive(
+                instance = _invoke_sql_with_hints(
+                    self.client.run_sql_interactive,
                     actual_sql,
+                    schema_aware=getattr(execution_settings, "version", "v2") == "v2",
                     **interactive_kwargs,
                 )
             else:
-                instance = self.client.run_sql(
+                instance = _invoke_sql_with_hints(
+                    self.client.run_sql,
                     actual_sql,
                     project=project,
                     hints=hints,
+                    schema_aware=True,
                     **idem_kwargs,
                     **priority_kwargs,
                 )

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/cli.py

@@ -251,7 +251,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Run or inspect a MaxCompute SQL statement",
         description=(
             "Run, estimate, or explain a MaxCompute SQL statement. "
-            "DDL/DML requires explicit --force.\n"
+            "SQL not proven read-only requires explicit --force.\n"
             "Usage:\n"
             f"  {cli_name} query \"SELECT 1\"             # default: run\n"
             f"  {cli_name} query run \"SELECT 1\"         # explicit run\n"
@@ -310,7 +310,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--force",
         action="store_true",
         default=False,
-        help="Allow one explicitly authorized data-plane DDL/DML statement (never inferred from a read request)",
+        help="Allow one explicitly authorized non-read SQL statement (never inferred from a read request)",
     )
     query_parser.set_defaults(handler=_handle_query)
 
@@ -357,7 +357,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--force",
         action="store_true",
         default=False,
-        help="Allow one explicitly authorized data-plane DDL/DML statement (never inferred from a read request)",
+        help="Allow one explicitly authorized non-read SQL statement (never inferred from a read request)",
     )
     job_submit.set_defaults(handler=_handle_job_submit, mcqa_fallback=None)
 
@@ -1713,14 +1713,12 @@ def run(
             "WRITE_OPERATION_REQUIRES_FORCE": AgentHints(
                 warnings=[
                     "This write gate is not authorization. Use --force only for "
-                    "one exact DDL/DML statement explicitly authorized by the user."
+                    "one exact non-read SQL statement explicitly authorized by the user."
                 ],
             ),
             "UNSUPPORTED_SQL_OPERATION": AgentHints(
                 warnings=[
-                    "The SQL shape is neither proven read-only nor recognized "
-                    "by the data-plane mutation allowlist; --force does not "
-                    "enable unknown or administrative operations."
+                    "Inspect the SQL error and the active execution context before retrying."
                 ],
             ),
         }
@@ -3372,7 +3370,7 @@ def _manifest_effects(command: str) -> list[dict[str, Any]]:
                 },
                 agent_allowed=True,
                 confirmation="--force plus exact user authorization",
-                note="One exact data-plane DDL/DML statement; verify project, schema, target, and effect.",
+                note="One exact non-read SQL statement; verify project, schema, target, and effect.",
             ),
             _manifest_effect(
                 "local",
@@ -3433,7 +3431,7 @@ def _manifest_effects(command: str) -> list[dict[str, Any]]:
                 },
                 agent_allowed=True,
                 confirmation="--force plus exact user authorization",
-                note="One exact data-plane DDL/DML statement; verify project, schema, target, and effect.",
+                note="One exact non-read SQL statement; verify project, schema, target, and effect.",
             ),
             _manifest_effect(
                 "local",

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/exceptions.py

@@ -164,13 +164,12 @@ class MaxCError(Exception):
             ],
             "WRITE_OPERATION_REQUIRES_FORCE": [
                 "This error is not authorization to write.",
-                "If the user explicitly requested the exact DDL/DML, verify its project, schema, target, and effect.",
+                "If the user explicitly requested the exact non-read SQL, verify its project, schema, target, and effect.",
                 "Submit that one statement with --force; never combine writes or infer one from a read request.",
             ],
             "UNSUPPORTED_SQL_OPERATION": [
                 "Use SELECT, SHOW, DESC, DESCRIBE, EXPLAIN, or a WITH query whose outer statement is read-only.",
-                "--force does not enable unknown, procedural, permission, session-control, or administrative SQL shapes.",
-                "Check the live command contract and use a dedicated approved workflow when the operation is outside the data-plane allowlist.",
+                "Inspect the SQL error and active execution context before requesting a new execution.",
             ],
         }
         return steps.get(self.error_code, [])

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/models.py

@@ -1025,15 +1025,14 @@ def build_safety_block(
     effective_hints: 'dict[str, str] | None' = None,
 ) -> 'dict[str, Any]':
     """Build a safety block describing the read-only policy state."""
-    from .utils import executable_operations, known_write_operations, statement_operations
+    from .utils import executable_operations, sql_requires_authorization, statement_operations
 
     if sql:
         operations = executable_operations(sql) or statement_operations(sql)
     else:
         operations = ["SELECT"]
-    write_operations = known_write_operations(sql) if sql else []
     operations = list(dict.fromkeys(operations or ["SELECT"]))
-    is_write = bool(write_operations)
+    is_write = sql_requires_authorization(sql) if sql else False
     rendered_hints = dict(effective_hints or {})
 
     if force:

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/skills/SKILL.md

@@ -177,19 +177,14 @@ examples only when these paths are insufficient.
 5. For partitioned tables, inspect `meta partitions` or
    `meta latest-partition`, then include an explicit partition filter.
 6. Cost-check broad or unfamiliar queries before execution.
-7. For DDL/DML, require an explicit user request and verify the exact statement,
-   project, schema, target, and effect. Submit one statement at a time with
-   `--force`; never infer a write from a read request, combine it with another
-   statement, or replay a suggested write action automatically. The CLI
-   positive allowlist accepts recognized data-plane mutations; permission,
-   account, project, system, resource, package, and unknown administrative SQL
-   remain blocked and require a dedicated approved workflow. A leading `SET`
-   is part of the authorized execution context, not a second authorization
-   channel: project-security and masking controls are always blocked, and a
-   forced mutation accepts only audited statement-local execution hints.
-   `data upload`,
-   `data download --overwrite`, and `job cancel` are separate mutations and
-   require authorization appropriate to their effect.
+7. SELECT, SHOW, DESC, DESCRIBE, EXPLAIN and proven read-only WITH queries
+   use the read path. Every other statement requires explicit user approval
+   of the exact SQL, leading SET context, project, schema, target and effect.
+   Submit that one statement with `--force`; MaxCompute validates its syntax,
+   SET parameters and permissions. SET keys do not change read/write classification.
+   A write-gate error is not authorization to replay the SQL.
+   `data upload`, `data download --overwrite` and `job cancel` are separate
+   mutations and require authorization appropriate to their effect.
 8. A failed command is not permission to retry indefinitely. Apply the
    suggested recovery once, then stop or ask when the target or authority is
    still unclear.

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/skills/references/command-patterns.md

@@ -175,8 +175,9 @@ With SET options (parsed and passed as hints to MaxCompute):
 
 Leading `SET` options are part of the remote execution context. They do not
 authorize a write or an administrative change. Project-security,
-access-control, and masking parameters are blocked; a forced mutation accepts
-only audited statement-local execution hints.
+access-control, and masking parameter validity and caller permissions are
+validated by MaxCompute. SET keys do not change read/write classification;
+there is no client-side operation or SET key allowlist or denylist.
 
 Legacy-compatible syntax still works:
 
@@ -186,7 +187,7 @@ Legacy-compatible syntax still works:
 
 The command is `query`, not `sql`. There is no `{{cli}} sql` command.
 
-For an exact DDL/DML statement the user has explicitly requested, first verify
+For an exact non-read SQL statement the user has explicitly requested, first verify
 the project, namespace, target, and effect, then submit only that statement:
 
 ```bash

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/skills/references/json-output-format.md

@@ -137,21 +137,17 @@ issuing a redundant `job result` call.
 
 ## Authorized SQL mutations
 
-DDL/DML is allowed only when the user explicitly requests the exact mutation.
-Verify the statement, project, schema, target, and effect, then submit one
-statement at a time with `--force`. The positive allowlist accepts recognized
-data-plane mutations; unknown, procedural, permission, session-control, and
-administrative SQL remain blocked even with `--force`.
-`WRITE_OPERATION_REQUIRES_FORCE` is a safety signal, not authorization; never
-infer the write or automatically replay a suggested mutation action.
-Leading `SET` options are part of the same authorized execution context.
-Project-security and masking controls remain blocked, and forced mutations
-accept only audited statement-local execution hints.
+SQL not proven read-only requires explicit user authorization for its exact
+statement, leading SET context, project, schema, target and effect. Submit one
+statement at a time with `--force`. The client accepts authorized operation
+names and SET keys without a positive allowlist; MaxCompute checks syntax,
+parameter validity and permissions. SET keys do not change read/write classification.
+`WRITE_OPERATION_REQUIRES_FORCE` is a safety signal, not authorization; obtain
+approval before any new submission.
 On successful query or submission responses, `data.safety.effective_hints`
 reports the hints actually sent to MaxCompute. Audited hint values are shown;
 an audited key whose value is outside its documented boolean, numeric, or enum
-domain is still rendered as `<redacted>`. Values of unknown hints retained for
-read-only compatibility are also never echoed.
+domain is still rendered as `<redacted>`. Values of unknown hints are never echoed, including for approved writes.
 
 ## data upload
 

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/skills/references/maxcompute-sql-notes.md

@@ -22,39 +22,27 @@ Multiple SET statements can be chained:
 
 For the meaning of each SET option (which switches enable which types / dialect features), see [maxcompute-select-guide.md](maxcompute-select-guide.md) §12.
 
-A leading `SET` is execution context, not authorization. Project-security,
-access-control, and masking parameters are blocked even for `SELECT`. For a
-forced DDL/DML statement, the CLI additionally accepts only audited
-statement-local SQL/runtime hints; an unknown hint fails closed. Never use a
-`SET` hint to weaken permissions, project protection, label security, or data
-masking.
-
-Audited write examples include `odps.sql.bigquery.compatible=true` for
-BigQuery-compatible DDL identifiers and
-`odps.sql.insert.acidtable.deduplicate.enable=true` for the explicitly requested
-Delta-table INSERT deduplication behavior. Their use still belongs to the same
-one-statement authorization; the hint is not separate permission to write.
+A leading `SET` belongs to the same authorized execution context as the SQL.
+Its syntax is parsed locally and its values are passed as hints to MaxCompute.
+There is no client-side SET key allowlist or denylist. SET keys do not change
+read/write classification. MaxCompute validates parameter keys, values and
+caller permissions.
 
 ## SQL Write Gate
 
-`maxc-cli` checks every executable operation, including operations nested in
-script control flow, **client-side, before submission**. Without `--force`, it
-submits only SQL shapes proven read-only. With `--force`, it still accepts
-exactly one executable statement; audited leading `SET` hints may configure
-that statement. The `odps.sql.read.only` hint is not injected.
+The client recognizes SELECT, SHOW, DESC, DESCRIBE, EXPLAIN and proven read-only
+WITH queries. Every other operation requires explicit user authorization and
+`--force`. New or administrative SQL is treated as a write; its operation name
+is not a client-side reason to reject an authorized statement.
 
-The gate is a safety aid, not authorization. For DDL/DML, require an explicit
-user request, verify the exact statement, project, schema, target, and effect,
-then submit one statement at a time with `--force`. Never infer a write from a
-read request or combine it with another statement.
+Verify the exact SQL, SET context, project, schema, target and effect, then
+submit one executable statement at a time with `--force`. MaxCompute owns
+syntax validation and permission checks. The `odps.sql.read.only` hint is not
+injected. A gate error is not permission to infer a write or automatically
+replay a suggested action.
 
-The `--force` path uses a positive data-plane allowlist. It accepts recognized
-DML and DDL for tables, views, functions, and schemas plus documented table
-maintenance or transfer statements. Permission, account, project, system,
-resource, package, tenant, cluster, quota, and unknown administrative shapes
-remain blocked; route those through a dedicated approved workflow.
-
-The gate applies to SQL only. **`{{cli}} data upload` is not gated** because it goes through the Tunnel API (a write path by design) — see "Upload semantics" below.
+The gate applies to SQL only. `{{cli}} data upload` is a separate Tunnel write
+path and retains its authorization and overwrite boundaries.
 
 ## Result Fetch: `--max-rows` and the 10k Tunnel Threshold
 

{maxc_cli-0.9.0 → maxc_cli-0.9.3}/src/maxc_cli/skills/references/red-lines.md

@@ -20,9 +20,9 @@ Cross-referenced with SKILL.md §Core Principles (which lists the highest-priori
 | 8 | Read `error.suggestion` before retrying a failed command | Same input → same error |
 | 9 | Do not replace an existing authentication method without authorization | Keep a working configured provider. For a new public-cloud login, recommend OAuth first; use another approved method only when policy or runtime constraints require it. |
 | 10 | Trust runtime help and actual command output over stale snippets | The CLI evolves; cached knowledge can be wrong |
-| 11 | Execute DDL/DML only when the user explicitly authorizes the exact statement, target, and effect; use `--force` one statement at a time | The gate is a safety aid, not authorization. Never infer or combine writes. (`data upload` is a separate write path and still needs authorization.) |
+| 11 | Execute non-read SQL only when the user explicitly authorizes the exact statement, target, and effect; use `--force` one statement at a time | The gate is a safety aid, not authorization. Never infer or combine writes. (`data upload` is a separate write path and still needs authorization.) |
 | 12 | Always check `agent_hints.warnings` even when `status=success` | Cache staleness, cost alerts, semantic gaps surface there |
-| 13 | Treat leading `SET` hints as part of the SQL execution context | Never use project-security, access-control, or masking parameters through `query`; forced writes accept only audited statement-local hints. |
+| 13 | Treat leading `SET` hints as part of the SQL execution context | Include SET context in the exact SQL being authorized. SET keys do not change read/write classification; key/value validity and permissions are checked by MaxCompute. |
 
 ## Common Mistakes
 
@@ -67,7 +67,7 @@ When `status=failure`, inspect `error.code` and follow the recovery action. Alwa
 | `SCHEMA_NOT_FOUND` | Schema does not exist | Check `error.context.did_you_mean` and `error.context.available_schemas`; list schemas with `meta list-schemas --json` |
 | `TABLE_NOT_FOUND` | Table does not exist in the schema | Check `error.context.did_you_mean` and `error.context.available_tables`; search with `meta search <name> --json` |
 | `COLUMN_NOT_FOUND` | Column reference does not exist | Check `error.context.available_columns`; run `meta describe <table> --json` |
-| `WRITE_OPERATION_REQUIRES_FORCE` | SQL DDL/DML blocked by the write gate | This is not authorization. If the user explicitly requested that exact write, recheck the statement, target, and effect, then retry once with `--force`; otherwise stop. This does not apply to the separately authorized Tunnel `data upload` command. |
+| `WRITE_OPERATION_REQUIRES_FORCE` | SQL not proven read-only blocked by the write gate | This is not authorization. If the user explicitly requested that exact write, recheck the statement, target, and effect, then retry once with `--force`; otherwise stop. This does not apply to the separately authorized Tunnel `data upload` command. |
 | `CSV_PARSE_ERROR` | A CSV cell could not be parsed against the column type during `data upload` | Read `error.context.line` (1-based row number, including header if present) and `error.context.column` (the column **name** as a string, not a position index) to find the bad cell; fix the source CSV and retry. File validation finishes before a Tunnel session is opened, so no rows are written. If `--create-partition` was explicitly requested, treat creation of an empty partition as a separate possible metadata side effect. |
 | `UPLOAD_COMMIT_OUTCOME_UNKNOWN` | The process was interrupted or the backend failed after the Tunnel commit request began, so remote visibility cannot be proven | **Do not retry the upload.** Verify the target table or partition first; retrying append can duplicate rows and retrying overwrite can replace a successful result. This error is non-recoverable and exits with code 130. |
 | `PERMISSION_DENIED` | The checked operation is not allowed for the effective identity/object | Verify identity, project/schema/object, then use `auth can-i` for that exact target |