@thinkingai/ae-cli 6.0.55 → 6.0.57

package/skills/ae-analysis/references/ai_models/event.md

@@ -87,14 +87,70 @@ Formula metric example:
 Formula rules:
 
 - Write **bare aliases** only in `formula` (e.g. `"revenue / users"` or `"pay / dau"`).
-- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Aggregation codes come from each dependency's `aggregation`; the builder expands aliases to real event tokens such as `purchase.amount.A103/login.A101`.
+- **Do not** write `alias.Axxx` (e.g. `"pay.A103"` / `"revenue.A103"`). Event aggregation codes come from that dependency's `aggregation`; saved-metric dependencies retain their own definition. The builder expands aliases to native event or saved-metric tokens.
 - Verify the complete formula through one analysis query and inspect its resolved definition and result before saving it. Reuse that result; a formula does not require a removed QP builder.
 
+## Formula operand filters
+
+For a new or intentionally rewritten formula, put each operand's conditions in that dependency's `filters`; `relation` joins its filters and defaults to `and`. These use the generic filter shape (`field`, `operator`, `values`, or an `items`/`relation` group), not the event-only `event_property_name` shape. Resolve event properties against that dependency's event. For example, only the numerator below requires the spring festival and `win=true`; the denominator remains unfiltered:
+
+```json
+{
+  "time_range": {"mode": "previous", "unit": "day", "value": 7},
+  "metrics": [{
+    "formula": "completed / participants",
+    "dependencies": [
+      {
+        "alias": "completed", "event": "activity_dungeon", "aggregation": "total_count",
+        "relation": "and",
+        "filters": [
+          {"field": {"type": "event_property", "name": "festival_name"}, "operator": "eq", "values": ["spring"]},
+          {"field": {"type": "event_property", "name": "win"}, "operator": "is_true"}
+        ]
+      },
+      {"alias": "participants", "event": "char_login", "aggregation": "total_count"}
+    ]
+  }]
+}
+```
+
+Replace the example events and properties with verified project metadata. Use `is_true` / `is_false` without `values` for boolean conditions; do not encode `win=true` as `eq` with `[true]` or `["true"]`.
+
+- To filter only the denominator, add `filters` only to its dependency. To give both sides different conditions, populate each dependency independently. One alias's filters apply to all its repeated occurrences; use different aliases for different filters on the same event. Binding follows expression occurrence order, not the order of `dependencies` and not deduplicated event names.
+- Do not move operand filters to root `definition.filters` or to the formula metric's common `filters`: these are shared calculation scopes, not a substitute for numerator/denominator conditions. Keep any intentionally supplied common filters independent of the dependency conditions; never copy an operand's conditions there as a fallback.
+- Compound groups use `{"relation":"and|or","items":[...]}`. Saved-report writes still obey the shared one-compound-level boundary; ad-hoc queries keep recursive support.
+- Filters on a saved metric dependency are not supported; the server rejects them rather than ignoring them. Preserve that metric's existing definition or use an explicitly verified ordinary event dependency. Do not expand or replace a saved metric merely to bypass this restriction.
+- Before using this shape on an older host, check its capability schema for dependency `filters` / `relation`. A new CLI alone does not add server compiler support. If unsupported, report the deployment prerequisite; never silently omit the operand filters.
+- Choose one formula representation. Native `formulation` or non-empty `custom_filters` must not be mixed with non-empty authoring `dependencies`; conflicting input is rejected rather than losing saved conditions or native UI metadata. For an unchanged saved formula, preserve all returned native fields and omit `dependencies`. To intentionally reauthor it, supply a complete reviewed formula/dependency definition and remove conflicting native fields; do not claim this preserves arbitrary native metadata. A supported `format` and display metadata may be kept.
+
+### Saved metrics as formula operands
+
+An event-report formula can reference verified saved metrics directly, without expanding their event definitions. Use each metric's discovered `metric_name` in the dependency's `event` field; it is not a metric ID or a numbered report measure. The compiler resolves the visible metric and preserves its calculation definition. Write only bare aliases in the expression:
+
+```json
+{
+  "time_range": {"mode":"previous","unit":"day","value":7},
+  "metrics": [{
+    "formula":"third / total",
+    "dependencies":[
+      {"alias":"third","event":"<verified_third_party_metric_name>"},
+      {"alias":"total","event":"<verified_total_metric_name>"}
+    ]
+  }]
+}
+```
+
+Replace placeholders with confirmed metric names from the current project. Omit `aggregation`, `property`, and `percentile` for saved-metric operands: the metric already owns these choices. Do not add dummy `total_count` or `sum` to satisfy a validation error. A mixed formula may combine this saved-metric shape with an ordinary event dependency that supplies its real aggregation and required property/percentile. Missing, inaccessible, or ambiguous metadata must follow compiler guidance; do not silently replace a saved metric with an event or inline a different calculation.
+
+A saved metric's own filters belong to its calculation; this is different from adding new `filters` to a saved-metric dependency, which remains unsupported. When creating a filtered metric for later formula reuse, follow [`metric_create.md`](../metric_create.md#saved-metric-filters) and verify its saved conditions with `analysis-meta metric get`. Reuse that verified metric by name without expanding or stripping its definition. To divide filtered replies by all replies, keep the filtered metric only in the numerator and use an independently verified unfiltered metric or event in the denominator; moving its conditions to the formula's common filters changes both sides.
+
+This is a formula inside an event analysis/report, not `analysis-meta metric create`, and it does not imply saved-metric dependency support for retention or other models. Existing saved-formula round-trip rules below still apply.
+
 Saved formula report round-trip rules:
 
 - `analysis report get` can return saved formula metrics with `custom_filters`, `formulation`, `custom_event_desc`, `event_desc`, `format`, `event_type`, `event_split_indexes`, `quota_time_ranges`, `quota_entities`, and `event_uuid`. These are saved-report round-trip fields, not the authoring shape for a new formula.
 - When updating an existing report from its returned `definition`, preserve all of those fields unchanged unless the user explicitly requests that formula behavior to change. `custom_filters[*].index` binds each numerator/denominator occurrence to its own filter set, including repeated event/aggregation tokens.
-- For a display-name-only change, modify only `display_name`. Do not convert the saved formula to `formula + dependencies`, because rebuilding dependencies can change or discard per-component filters and other formula semantics.
+- For a display-name-only change, modify only `display_name`. Do not convert the saved formula to `formula + dependencies`; reauthoring is a different operation and cannot preserve arbitrary native metadata automatically. Mixed representations are rejected as described above.
 - Continue to use the `formula + dependencies` shape above when authoring a new formula metric.
 
 Saved report filter round-trip rules:

package/skills/ae-analysis/references/ai_models/rank_list.md

@@ -31,6 +31,7 @@ Use for ranking users/entities by an event metric.
 - `accompanying_properties` is an array of field dimensions. The main `rank_dimension` and accompanying properties support `array_grouping`, `time_granularity`, and historical tag/cluster date policies. Numeric buckets, funnel steps, and retention sources are not rank-list options.
 - For formula ranking, set `rank_formula` to a formula metric definition. Omit the mutually exclusive regular metric fields `rank_event`, `rank_aggregation`, `rank_property`, `rank_filters`, `rank_relation`, and `rank_quota_entities`; put formula filters inside `rank_formula.filters`. Keep the outer `order_by` as `ASC` or `DESC`.
 - Formula dependencies and accompanying metrics use the same aggregation restrictions as the primary metric, including the exclusion of `percentile`. Preserve saved formula metadata returned by report reads.
+- Both `rank_formula` and accompanying formulas support [operand-specific filters](event.md#formula-operand-filters) in each dependency's `filters` / `relation`, using generic `field` leaves. Keep these separate from the formula's common filters and the definition's global filters; rank-list aggregation and saved-metric restrictions still apply.
 
 ```json
 {

package/skills/ae-analysis/references/ai_models/retention.md

@@ -86,6 +86,8 @@ Place this object inside `retention`. `combine_operator` belongs to `initial_dat
 
 Both roles support `formula` and `dependencies` with the same retention aggregation restrictions. Use bare aliases for new formulas. Preserve returned `formulation` and `custom_filters` when updating a saved formula; they carry the native dependency metadata and filters. Metric `filters` use event-only leaves and support recursive `items`/`relation` groups.
 
+For conditions on just one formula operand, use that dependency's `filters` / `relation` as described in [formula operand filters](event.md#formula-operand-filters). Dependency leaves use the generic `field` shape, unlike the simultaneous metric's event-only filters. Do not replace operand conditions with shared metric filters; retain retention's aggregation and saved-metric restrictions.
+
 `relation_event_property_name` supplies a shared relation property. `initial_relation_event_property_name` and `return_relation_event_property_name` override it for the two cohort events; both must resolve whenever either is configured. A `return_users` metric can override `relation_event_property_name` for its own event. All relation properties must have compatible types; relation overrides do not apply to `initial_date`.
 
 ## Grouping and summary settings

package/skills/ae-analysis/references/ai_models/revenue.md

@@ -44,3 +44,5 @@ Both `revenue_metric` and `cost_metric` accept a formula with alias dependencies
 ```
 
 Number formats are `float`, `float3`, `float4`, `integer`, and `percent`. Saved formulas may contain an expanded `formula`, `formulation`, and `custom_filters`; preserve that metadata on updates. Event and regular-metric filters support recursive `items`/`relation` groups using event-property leaves. `first_day_of_week` is between 1 (Monday) and 7 (Sunday).
+
+Formula dependency `filters` / `relation` support [operand-specific conditions](event.md#formula-operand-filters) using the generic `field` shape. Put revenue/cost numerator and denominator conditions in their own dependencies, not in the formula metric's mutually exclusive `filters` / `relation`. Revenue aggregation and saved-metric restrictions still apply.

package/skills/ae-analysis/references/analysis_data_export.md

@@ -10,7 +10,15 @@ ceilings.
 
 `--artifact-format` selects the logical row format, not compression. Read the returned `format`, `compression`, `file_name`, `content_type`, and `content_encoding`; analysis query exports are currently gzip-compressed even when the logical format is `jsonl` or `csv`.
 
-Default and maximum runtime is 21600 seconds (6 hours). Omit `--timeout-seconds` to use that default, or pass a smaller value when the caller explicitly wants an earlier deadline.
+Omit `--timeout-seconds` to use the server default (normally 21600 seconds / 6 hours). Common analysis-query and asset-governance exports use the deployment's async default, which may exceed 6 hours. The analysis-query typed flag still accepts explicit values only in `1..21600` (asset-governance typed flags retain `1..7200`); inspect the selected capability for the server default and maximum. If its schema allows a larger explicit value, use `capability run` with `timeout_seconds`. Other export families retain their own server policies; do not assume this deployment setting applies to every export.
+
+Read `effective_timeout_seconds`, `timeout_source`, and `deadline_at` from the returned run descriptor for the actual deadline.
+
+The member's natural-day quota counts each Gateway capability `execute` call eligible for usage statistics: the user is identifiable and statistics are enabled. Eligibility follows Gateway usage recording, regardless of business purpose or database engine (including MySQL and Trino). Report reads/saves, metadata reads, asset-governance exports, business data queries, cache hits, and failures that reach `execute` all count. This includes invalid input schemas, permission denials, unknown capability IDs, and accepted work that later fails or times out. A local CLI validation failure that never reaches Gateway `execute` does not count.
+
+Each repeated `execute` call counts, even with identical input or when a handler reuses an existing run. Gateway provides no general `client_request_id` idempotency guarantee. Resume the existing run through its status/download endpoints instead of submitting it again. Gateway capability-discovery list/inspect endpoints, validate/dry-run endpoints, and independent run-status/artifact-download HTTP endpoints do not enter capability execution and do not count. This applies to `analysis run inspect`, `analysis run wait` polling, and `analysis artifact download`. Business `list`/`get` commands still count when they execute a capability; the operation's name does not change its route. Pagination, cancellation, or another operation invoked through capability execution does count; for example, both `analysis query cancel` and `capability run analysis.query.cancel` enter `execute`.
+
+`QUERY_DAILY_LIMIT_EXCEEDED` (HTTP 429) requires waiting until reset or contacting an administrator. A call blocked at the daily limit does not increase the used quota, but remains eligible for failed-call usage auditing. `QUERY_QUOTA_UNAVAILABLE` means quota enforcement is unavailable and fails explicitly. Do not retry with another identity to bypass either error. Usage persistence is asynchronous and best effort: quota and usage recording share eligibility, but the quota counter need not equal the number of persisted usage rows.
 
 Choose one lifecycle form:
 
@@ -36,6 +44,8 @@ or a persistent transient network failure stops only local waiting; it never
 cancels the remote run. Resume with the returned `resume_command` or printed
 `analysis run wait` command.
 
+A server run can outlive one local wait window. Resume the same run instead of submitting it again.
+
 Waiting succeeds only for `status=SUCCEEDED` plus
 `artifact_status=COMPLETED`. Run or artifact `FAILED`/`CANCELED` is terminal and
 returns a non-zero error. Unknown states, authorization failures, and 404s fail

package/skills/ae-analysis/references/asset_batch_info_export.md

@@ -12,7 +12,7 @@ ae-cli analysis-governance asset batch-info-export --project-id <project_id> --n
 
 Capability id: governance.asset.batch_export_info.
 
-Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` (1..7200, default 3600) may be supplied through `--payload`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
+Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` may be supplied through `--payload`; inspect the capability for the server default/range. The explicit `--timeout-seconds` flag retains its `1..7200` range. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Inspect and download the returned artifact IDs.
 
@@ -29,6 +29,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

package/skills/ae-analysis/references/asset_batch_sql_export.md

@@ -14,7 +14,7 @@ ae-cli analysis-governance asset batch-sql-export --project-id <project_id> --no
 
 Capability id: governance.asset.batch_export_sql.
 
-Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` (1..7200, default 3600) may be supplied through `--payload`. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
+Input sends `project_id` and `node_ids`. Optional `request_id`, `format` (only `xlsx`), and `timeout_seconds` may be supplied through `--payload`; inspect the capability for the server default/range. The explicit `--timeout-seconds` flag retains its `1..7200` range. The CLI merges the snake_case object from `--payload` into these top-level Gateway fields; explicit flags override matching payload fields. `--project-id` owns the project identity and cannot be supplied or overridden by payload. Required business fields must exist in the final merged input.
 
 Output `data` is an async XLSX descriptor with `run_id`, `artifact_id`, status, and expiry fields. Alternatively, wait and download with `ae-cli analysis run wait --run-id <run_id> --output <file>` using the returned run ID; see [`run_wait.md`](run_wait.md).
 
@@ -31,6 +31,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format xlsx` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

package/skills/ae-analysis/references/asset_export.md

@@ -35,6 +35,6 @@ This capability starts an asynchronous artifact export. Use `--wait --output <pa
 
 - `--artifact-format jsonl` selects the logical data format. Follow the returned descriptor for compression and content type.
 - `--request-id cli_<32 lowercase hex>` assigns a stable request identifier.
-- `--timeout-seconds` accepts 1–7200 (server default: 3600).
+- Omit `--timeout-seconds` to use the server-provided default. This typed CLI accepts explicit values in `1..7200`; inspect this capability for the deployment default/max. Use `capability run` with a larger explicit `timeout_seconds` only when its schema permits it.
 - `--wait-timeout-seconds` controls how long this CLI invocation waits; it does not change the server runtime limit.
 - Explicit flags override corresponding `--payload` fields; omitted options preserve payload values.

package/skills/ae-analysis/references/bi_panel_page_data_export.md

@@ -12,7 +12,7 @@ Command:
 ae-cli analysis bi-panel-page-data export --project-id <project_id> --panel-id <panel_id> --page-key <page_key> --result-type charts [--chart-ids '["chart1"]'] [--artifact-format jsonl] --output <file>
 ```
 
-Input sends `project_id`, `panel_id`, `page_key`, `result_type=charts`, and optional chart, control, column, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. The export does not accept row/block paging fields: Common streams chart rows directly and applies only `model_full_download_limit`. Runtime defaults to and is capped at 21600 seconds (6 hours); cancel earlier with `analysis query cancel --run-id <run_id>`. BI summary is rendered presentation data; query it with `bi-panel-page-data run`.
+Input sends `project_id`, `panel_id`, `page_key`, `result_type=charts`, and optional chart, control, column, cache, request, timeout, and format fields. Use CLI flag `--artifact-format` for the gateway `format` input; `--format` is the CLI output formatter. The export does not accept row/block paging fields: Common streams chart rows directly and applies only `model_full_download_limit`. Omit `--timeout-seconds` to use the deployment's server default (normally 21600 seconds / 6 hours). The typed CLI accepts explicit `1..21600`; inspect this capability for the server default/max and use `capability run` for larger explicit values only when allowed. Read the run descriptor for the effective deadline; cancel earlier with `analysis query cancel --run-id <run_id>`. BI summary is rendered presentation data; query it with `bi-panel-page-data run`.
 
 Output is the gateway envelope. `data` contains an async export descriptor with `run_id`, `artifact_id`, status fields, and expiration fields. It does not create `query_context_id`. The CLI handles waiting and download with `--output`.
 

package/skills/ae-analysis/references/check_export.md

@@ -23,5 +23,5 @@ Parameters:
 | `--project-id` | Numeric project ID. | Yes |
 | `--uuid` | Tracking check task UUID. | Yes |
 | `--request-id` | Optional caller-supplied cli_<32 lowercase hex> lifecycle ID. ae-cli generates and prints one before dispatch when omitted. | No |
-| `--timeout-seconds` | Async runtime in seconds. Default and max: 21600 (6 hours); cancel earlier with analysis query cancel --run-id <run_id>. | No |
+| `--timeout-seconds` | Async runtime in seconds. Omit to use the server default (normally 21600 / 6 hours). Explicit CLI values remain in 1..21600. Inspect the capability for its server default/max; use capability run for larger values only when allowed. Cancel with analysis query cancel --run-id <run_id>. | No |
 | `--output` | Wait and download to this local file. | No |