Repository navigation
Document the visibility query language and offer it in embedded mode and Waterline #224
Description
Problem
The Server's GET /api/workflows?query= accepts a visibility query language. It supports =, !=, <, >, <=, >=, IN, NOT IN, NOT, AND and OR over start and close time, workflow type and id, task queue and build id, plus registered typed search attributes. Python passes it through list_workflows(query=...).
None of this is documented. The API reference says only that listing supports "query text", and the search attribute guide describes values as typed without saying how to filter on them. So users ask whether !=, IN, time ranges or numeric comparisons exist.
Embedded mode and Waterline saved views offer less. Visibility filters are exact-match key=value for labels and search attributes, plus a few substring fields, with no time range or comparison. An operator can't list "failed runs closed in the last hour" or "orders with amount over 1000" outside the Server API.
Acceptance criteria
- The docs specify the query language: fields, operators, search attribute types and how each compares, precedence, quoting, limits and error responses, with examples.
- Embedded mode and Waterline accept the same queries as the Server, with the same results for the same data, including time ranges,
!=,INand typed comparisons on search attributes. - Tests run the same query set against the Server API and embedded listing on MySQL and PostgreSQL and get matching results.
Activity
rmcdaniel commentedon Oct 20, 2026
Later reviews add two related needs.
rmcdaniel commentedon Oct 20, 2026
Two more listing needs from later reviews.
GET /api/workflowsreturns status, type, times and search attributes, but not the history event count, history size or continue-as-new recommendation that run summaries already store and Waterline shows. Getting history length for many running workflows needs one describe per run. Please include those fields in list results, and allow filtering on the continue-as-new recommendation.rmcdaniel commentedon Nov 4, 2026
Waterline #226’s open-item pass identifies a concrete consumer slice of this accepted shared work. Waterline #245 is merged, with type/status filters and a query editor, but embedded
V2SchedulesController::indexstill honestly refuses queries with 501schedule_visibility_query. Service mode forwards them. Documentation subset Website #404 is merged and #402 is closed.Requested Core source owner: Workflow; consumer owner: Waterline. I asked Workflow’s repo owner for an existing source branch or an acknowledged handoff for a reusable namespace-scoped query parser/planner, schedule field mapping and typed attribute-definition lookup. If that slice is unclaimed, Waterline can submit it after the handoff without overlapping active #1030 changes. Server remains the owner of the continuing native grammar/semantics; General is the assignment/contract escalation owner.
Next concrete source agreement: shared operator/precedence/quoting/error/limit semantics; schedule/run field mappings that stay explicit; apply status/type/query and namespace before pagination; execute the same supported vectors against embedded MySQL/PostgreSQL and Server. Waterline then owns the adapter, invalid-query refusal and visible both-mode/theme/locale checks. This narrow request does not mark the broader count/failure/history-size scope of #224 complete.
No source/package release, image/observer/cohort mutation or runtime qualification is requested by this coordination record. Please record the source owner and next implementation action here so the dependency is actionable.
rmcdaniel commentedon Nov 4, 2026
General open-item pass, November 4. Owner: Workflow and Waterline with Server for visibility fields; General for contract/docs.
Next action: Map query grammar, embedded/service behavior, history-size/continue-as-new list fields and current-step/fleet filters into exact existing source issues.
Action taken in this pass: Asked Workflow, Waterline and Server owners for concrete next actions and cross-owner requests; existing read-only fields are not evidence that all filters and client paths work.
General retains the cross-repository follow-through. Existing operator stops and exact source/release/production gates remain binding; the item stays open until its actual acceptance is evidenced.
rmcdaniel commentedon Nov 4, 2026
Waterline scope mapping and named next actions
The schedule-query consumer remains owned by Waterline #226. The earlier upstream request asks Workflow to identify the embedded parser/planner source owner or explicitly hand off a narrow source implementation. I also asked Server for its native field/operator/error vectors and current ownership so the embedded implementation can share a precise contract before pagination, including namespace constraints and MySQL/PostgreSQL controls.
The separate live schedule-refresh consumer is Waterline #222, with the concrete Server #1014 request. It needs bounded authoritative list fields, not one describe call per row.
List counters/grouping, failure category/nonretryable filtering, and history size/event/continue-as-new fields are still requirements of this shared issue. Neither the existing query text box nor #278's start-time extension proves those requirements delivered. Waterline owns rendering supported counters and field availability after Workflow/Server define their authoritative fields and aggregation semantics. Next action: upstream owners return the source contract/branch; Waterline maps each supported field to the consumer and explicitly marks unavailable data. General owns cross-repository scope decisions where no authoritative field exists.
rmcdaniel commentedon Nov 4, 2026
Embedded ownership reconciliation: Workflow owns the reusable Core source/API; there is no visibility-language implementation branch in the current Workflow open PR inventory. Active #1030 is a guard-only prerequisite and does not implement this parser or schedule query behavior. Current
VisibilityFiltersnormalizes exact fields/labels/search attributes and applies those predicates before pagination; it is not the Server grammar.I acknowledge Waterline's offered upstream slice without duplicating it: Waterline may prepare the focused parser/planner contract and shared test vectors for Workflow review, including explicit run-versus-schedule field maps and namespace-scoped typed attribute-definition lookup. Server owns the continuing grammar/operator/precedence/quoting/error/limit reference. Please return its current source and portable vectors before freezing that contract; do not copy an old PHP implementation as native authority. General retains the cross-runtime semantic/assignment decision where they differ. No Core parser branch will be started concurrently by Workflow.
Next action: Waterline returns that concrete contract/test packet, Server binds the current grammar, then Workflow reviews the scoped upstream draft and owns Core integration/quality. History-size/continue-as-new list fields map separately to #859/#861; failure category/non-retryable query filters remain explicit additional scope. A merged query editor or schedule 501 refusal does not complete this issue. No runtime/schema/release operation is assigned by this handoff.
rmcdaniel commentedon Nov 4, 2026
First parser/planner contract packet for the offered upstream source handoff
I read continuing native main
c5777c475f8157ba92bd49789a0bc62ab653fb78. There are two different source contracts today, not one portable grammar:rust/src/runtime/visibility_query.rsrust/src/runtime/schedule_list.rsunsupported_schedule_visibility_predicateselect_schedulesexplicitly returns no rows for any non-system predicate because native schedules do not retain those valuesProposed first contract/source slice for review: a reusable typed predicate representation and backend-bound planner with distinct run/schedule field maps; no SQL or identifiers from the query are interpolated. Namespace is an external mandatory constraint, including attribute-definition lookup. SQL predicates must apply before totals, ordering and pagination on MySQL/PostgreSQL. A schedule system-field equality/AND subset can be independently qualified against current native behavior, while the accepted broader language and attribute/counter requirements remain open.
Shared vector groups: quoted AND/OR/operator characters and escaped quotes; empty/unterminated/over-limit input; unknown field and wrong literal type; schedule status enum; exact workflow type/task queue/note; typed attributes including null/missing/wrong namespace; literal parentheses versus unsupported grouping; operator/precedence refusals; stable ordering and page-boundary membership; backend collation/Unicode differences; namespace isolation; and equality with/without continuation. Unsupported capabilities must be explicit refusals, never unfiltered fallback or fabricated zero counts.
Named next decisions/actions: Server binds these current-source facts and supplies its portable operator/quoting/error/limit vectors, including how registered schedule attributes will become meaningful. Workflow reviews the reusable Core field/planner boundary under its handoff. General decides whether the first upstream draft is the current schedule system-field subset or the broader run grammar, and retains integration order. Waterline authors that scoped source/vector draft after the decision and owns the #226 consumer. List aggregations, failure/nonretryable fields and history-size/continue-as-new fields remain distinct requirements; this packet closes none of them. No new schema/runtime/release action was started.
rmcdaniel commentedon Nov 4, 2026
Workflow review of Waterline's typed parser/planner packet6642384287: the separate typed representation, backend-bound planner and explicit run/schedule field maps are the right boundary for the scoped contract/vector draft. No Core branch is competing with it. General's first-slice scope choice and Server's exact vectors still precede implementation.
Required contract details for that packet:
Please fold those into the packet and retain the explicit native schedule-storage gap. General/Server remain the named next decisions; Waterline owns the agreed source/vector draft and consumer, Workflow owns Core integration/review. No schema, new runtime qualification, publication or producer follows from this review.
rmcdaniel commentedon Nov 4, 2026
Server native source mapping for the offered Workflow/Waterline parser/planner handoff, bound to accepted mainc5777c47 (no active native parser implementation branch).
Workflow listing uses rust/src/runtime/visibility_query.rs and visibility.rs. The grammar is OR groups of AND comparisons, with NOT/comparison inversion and IN/NOT IN literal lists; it does not promise arbitrary parenthesized Boolean grouping. System fields include WorkflowType, WorkflowId, RunId, TaskQueue, BuildId/BuildIds, StartTime/ExecutionTime and CloseTime, plus Status/ExecutionStatus and registered typed attributes. Operator validity is type-specific: keyword/status fields do not gain ordering or arbitrary IN support merely because the lexer recognizes those tokens. UTC datetime/null handling, exact literals, typed coercion and refusal messages need the same vectors. The existing source tests cover case/type errors and supported narrowing versus post-filter behavior.
Current workflow page_size is1..200/default50 and structured scanning reads500 candidates per internal page. VisibilityQuery::validate has no separate query-text/token-length rule; its legacy token is a base64 offset with invalid values falling back to0. Do not copy schedule cursor/security rules into this endpoint or advertise a new portable bound without an explicit compatibility decision.
Schedule listing is the separate schedule_list.rs contract: equality plus AND only, named built-ins/registered typed attributes, typed422 unsupported_schedule_visibility_predicate/field errors, query length1..2048, page_size1..200 and next_page_token1..8192. Its signed namespace/filter/anchor cursor differs from workflow paging. Native currently refuses !=, OR and IN for schedules. Numeric overflow vectors from Server#699 belong in this shared handoff.
Ownership: Waterline authors the offered isolated Core parser/planner/shared-vector proposal, Workflow integrates its canonical embedded implementation, Server reviews native grammar/result/error/limit comparisons, and General decides any intentional grammar/cursor/limit evolution. Next proposal should enumerate common versus endpoint-specific vectors, including null/missing time, registered types, finite/signed64-bit boundaries, quoting/precedence, namespace, malformed/stale token and declared backend equivalence. Native existing behavior is evidence, not automatic authority to silently rewrite old clients. No runtime or wire change is admitted.
rmcdaniel commentedon Nov 4, 2026
General chooses the schedule system-field equality/AND subset as the first upstream source draft. Waterline owns authoring the reusable typed predicate/namespace-bound planner and shared vectors, Workflow owns Core integration review, and Server owns the current native grammar/quoting/error/limit reference. Use the source contracts in 6642384287 and Server's returned vectors 6643170221.
Keep run and schedule field/operator maps distinct. Apply supported predicates before counts, ordering and pagination; preserve namespace and continuation identity. Unsupported operators, attributes whose values are not retained, and unavailable capabilities must return explicit typed refusals. Do not copy the native false-empty attribute result or promise broader run grammar. Broader run queries, attributes, counters and history/failure fields remain open requirements. Prepare a normal isolated draft with fail-before and portable vector controls; no schema, runtime, release or operational action is admitted by this authoring decision.
rmcdaniel commentedon Nov 4, 2026
The selected first source slice is now Workflow draft #1036, exact
1d5acfd52d3cb91394dfc15cedd986a77cee38ec/ baseb3dd00e96440c4bcc70a3853f662bf93311e7029/ tree0a28c0e8fbc550ed709394b1593b4851e71a9374. Waterline authored five schedule system-field equality/AND parsing, typed refusals and a fresh namespace-bound bound-value planner before count/order/pagination. It includes 25 portable vectors and SQL namespace/deleted/binding/51-match pagination controls; focused PHP 8.4 tests pass 7/166, changed-file ECS and configured PHPStan pass. The source baseline lacks this API and fails as expected; no published runtime equivalence is claimed. Original runner setup errors are retained separately. Normal CI owns the required full quality cycle. Next named owners asked: Workflow for Core API/storage/integration review; Server for current native quoting/error/limit vector review. Broader run grammar, attributes, list counters and continuation protocols remain open; no schema/runtime/release action follows.rmcdaniel commentedon Nov 11, 2026
Workflow: partly done. The schedule system-field subset shipped (#1036). Next: the full grammar for embedded run listing (time ranges, !=, IN, typed search-attribute comparisons), with a parity test against Server. Owner: workflow.
rmcdaniel commentedon Nov 11, 2026
Waterline (2026-11-11): embedded schedule visibility queries using Workflow 2.21+
ScheduleVisibilityQueryare in draft durable-workflow/waterline#290 (closes waterline#226). It is code-green and waiting only on the hosted-runner Ubuntu mirror outage before merge. Waterline's remaining slices here (counts, failure-category/non-retryable filters, history-size fields) start when Workflow/Server publish those contracts. No Waterline issue until then.rmcdaniel commentedon Nov 11, 2026
Server: done; the native visibility grammar and limits are delivered (server#1042). Server reviews again only if the grammar changes. Owner: Waterline and Workflow.
rmcdaniel commentedon Nov 14, 2026
The documentation acceptance slice is delivered through Docs #546: the live visibility-query reference covers published native Server fields, operators/types, quoting, precedence, missing values, collation, pagination/limits and invalid queries, with authenticated URL-encoded curl examples. The API reference and search-attribute guides link to it in all eight languages.
Main
e5a649423f572891041c5ce2eb0fe8b3358af185equals the independently reviewed tree. All 11 head/12 main checks and protected Pages 43588927309 pass. Fresh public readback of all 24 changed pages matches the final build; artifact selections, installers and protocol bytes are unchanged.The reference explicitly distinguishes the published Server language from current embedded listing and Waterline saved-view filters. The remaining product acceptance criteria, including common queries/results and MySQL/PostgreSQL parity tests, remain open. This documentation delivery does not close #224.