objectstack-ai
diff --git a/‎.changeset/list-runs-status-filter.md‎
Lines changed: 75 additions & 0 deletions b/‎.changeset/list-runs-status-filter.md‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎packages/client/src/index.ts‎
Lines changed: 11 additions & 3 deletions b/‎packages/client/src/index.ts‎
Lines changed: 11 additions & 3 deletions
diff --git a/‎packages/runtime/src/domains/automation-runs-query-validation.test.ts‎
Lines changed: 122 additions & 20 deletions b/‎packages/runtime/src/domains/automation-runs-query-validation.test.ts‎
Lines changed: 122 additions & 20 deletions
@@ -0,0 +1,75 @@
+---
+"@objectstack/spec": minor
+"@objectstack/client": minor
+"@objectstack/runtime": patch
+"@objectstack/service-automation": patch
+---
+
+fix(spec,runtime,service-automation): `GET /automation/:name/runs?status=` filters the runs instead of being dropped (#7359)
+
+`ListRunsRequestSchema` has always declared a `status` filter on
+`GET /api/automation/:name/runs` — `z.enum([...the eight ExecutionStatus
+members]).optional()`, described as "Filter by execution status". Nothing read
+it. It had no slot on `IAutomationService.listRuns`, whose options were
+`{ limit?, cursor? }`, and the runtime handler never built it into the object it
+forwarded, so the parameter was dropped at the HTTP boundary and the caller was
+answered **200 with every run of the flow**, capped by `limit`.
+
+That is worse than an error, because the answer looks like the one that was
+asked for: a monitoring caller paging `?status=failed` reads the first 20 runs
+of any status and concludes those are the failures. Exposure was raw HTTP,
+generated clients, and anything authored against the OpenAPI surface — the typed
+SDK could not send the parameter at all, which is why nothing had tripped over
+it. #7300 fixed this route's two *coerced* parameters and deliberately preserved
+the ignore-the-key behaviour rather than decide between honouring and retiring
+the third; this change takes the enforce route (ADR-0049), so the declared
+surface is now true.
+
+**The filter is honoured across both stores.** `AutomationEngine.listRuns`
+serves the Runs view by merging an in-memory ring buffer with the durable run
+history it reads back from the store. The narrowing is applied to the merged
+result, so both halves are covered: filtering only the buffer would answer "no
+failures" for a flow whose failures are all in durable history — i.e. after any
+restart, which is exactly when someone asks — and filtering only the durable
+rows would hide the live ones. Applying it after the merge also means each run
+is matched on its **resolved** status: the buffer holds more than one entry per
+run id (a run that pauses appends `paused`, then its terminal entry), and
+narrowing before the collapse would have let a stale `paused` entry outlive the
+terminal one, so every approval/screen/wait run that had since completed would
+report itself as still paused.
+
+The durable arm's window is unchanged: `listHistory(flowName, limit)` has no
+status slot, so the filter is applied to the rows that come back rather than
+pushed down, and a status filter can therefore return fewer than `limit` matches
+while older ones exist. That is this merge's pre-existing shape — durable rows
+were already capped at `limit` before the sort-and-slice — and closing it is a
+store-contract change. What it never does is return a run of another status.
+
+**An undeclared status is now refused, not silently widened.** Once the filter
+is honoured, a value outside the set has no safe reading: `?status=faild` cannot
+mean "no filter", and serving the empty list is no better, because "no runs are
+`faild`" and "no runs failed" read identically to a caller who cannot see their
+own typo. The check goes through the shared `query-param` module this route
+already consumes with `/notifications`, as a new `parseEnumParam` gate, and
+refuses in the house shape — `400` `VALIDATION_FAILED` (ADR-0112) with a
+`details.fields[]` entry carrying ADR-0114's existing `invalid_option`
+("not a member of the field's declared options"); a value that was never a
+single string at all — a repeated `?status=a&status=b`, a structured
+`?status[$ne]=x` — gets `invalid_type`, the same mapping the module's string
+gate already makes. No new error vocabulary. The accepted members are read from
+the spec's own `ExecutionStatus` enum, the one `ListRunsRequestSchema` is built
+from, so the wire's declared set and the boundary's accepted set cannot drift.
+
+**The typed client can now send it.** `client.automation.listRuns(flow, {
+status })` — both the `automation.listRuns` alias and `automation.runs.list` —
+takes the filter as an optional `ExecutionStatus`, additively. It could not send
+the parameter at all before, which is the reason nothing had tripped over the
+server-side gap; leaving it out would have made the enforced filter reachable
+only from raw HTTP, and the Runs view that wants it goes through this client.
+
+**Nothing that had a defensible answer changes.** An absent `status` still
+returns every run, exactly as before. So does the empty spelling `?status=` —
+unlike `?read=` on the notifications inbox, which used to serve the wrong *half*
+of the result, `?status=` already served precisely what "no filter" means, and
+it is what an "All statuses" `<select>` submits. `limit` and `cursor` are
+untouched, including out-of-range values, which remain the service's business.
@@ -83,6 +83,7 @@ import type {
   ApprovalStatus,
   ApprovalDecisionResult,
 } from '@objectstack/spec/contracts';
+import type { ExecutionStatus } from '@objectstack/spec/automation';
 import { Logger, createLogger } from '@objectstack/core/logger';
 import { RealtimeAPI } from './realtime-api';
 
@@ -3130,12 +3131,17 @@ export class ObjectStackClient {
       /** Alias for `automation.runs.list`. */
       listRuns: async <T = any>(
           flowName: string,
-          opts?: { limit?: number; cursor?: string },
+          opts?: { limit?: number; cursor?: string; status?: ExecutionStatus },
       ): Promise<T> => {
           const route = this.getRoute('automation');
           const params = new URLSearchParams();
           if (opts?.limit != null) params.set('limit', String(opts.limit));
           if (opts?.cursor) params.set('cursor', opts.cursor);
+          // [#7359] The route's declared `status` filter, now that the boundary
+          // honours it instead of dropping it. Until this card the typed client
+          // could not send it at all — which is why nothing had tripped over the
+          // server-side gap.
+          if (opts?.status) params.set('status', opts.status);
           const qs = params.toString();
           const res = await this.fetch(
               `${this.baseUrl}${route}/${encodeURIComponent(flowName)}/runs${qs ? `?${qs}` : ''}`,
@@ -5261,14 +5267,16 @@ export class ScopedProjectClient {
       });
       return this.parent._unwrap<T>(res);
     },
-    /** List recent runs for a flow. */
+    /** List recent runs for a flow, optionally narrowed to one status. */
     listRuns: async <T = any>(
       flowName: string,
-      opts?: { limit?: number; cursor?: string },
+      opts?: { limit?: number; cursor?: string; status?: ExecutionStatus },
     ): Promise<T> => {
       const params = new URLSearchParams();
       if (opts?.limit != null) params.set('limit', String(opts.limit));
       if (opts?.cursor) params.set('cursor', opts.cursor);
+      // [#7359] — see the sibling `listRuns` alias above.
+      if (opts?.status) params.set('status', opts.status);
       const qs = params.toString();
       const res = await this.parent._fetch(
         this.url(`/automation/${encodeURIComponent(flowName)}/runs${qs ? `?${qs}` : ''}`),
 
@@ -1,7 +1,18 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #7300 — `GET /api/v1/automation/:name/runs`'s coerced query parameters.
+ * #7300 / #7359 — `GET /api/v1/automation/:name/runs`'s query parameters, at
+ * the boundary that reads them.
+ *
+ * #7300 (below) closed the two parameters this handler already forwarded but
+ * COERCED. #7359 closed the third, which is the same 200-with-the-wrong-answer
+ * arrived at from the opposite direction: `status` was declared by
+ * `ListRunsRequestSchema`, had no slot on `IAutomationService.listRuns`, and
+ * was never built into the handler's option object — so `?status=failed` was
+ * dropped here in silence and the caller was answered with EVERY run of the
+ * flow. #7300 deliberately pinned that ignore-the-key behaviour rather than
+ * decide it; #7359 took the enforce route, so that one pin is superseded here
+ * by cases asserting the opposite on the same input.
  *
  * The filed defect is character-for-character #6928's, one file over:
  * `{ limit: query.limit ? Number(query.limit) : undefined, cursor: query.cursor }`.
@@ -132,6 +143,60 @@ describe("#7300 — the same probe on this route's other passed-through paramete
     });
 });
 
+describe('#7359 — a `?status=` outside the declared set is refused, not silently widened', () => {
+    it.each([
+        ['a typo', 'faild'],
+        ['right word, wrong case', 'FAILED'],
+        ['a status of a neighbouring vocabulary', 'success'],
+        ['empty-ish but not a member', ' '],
+    ])('refuses ?status=%s with 400 VALIDATION_FAILED', async (_label, raw) => {
+        // Once the filter is honoured there is no safe reading left for a value
+        // outside the set. `?status=faild` cannot mean "no filter" — the caller
+        // plainly asked to narrow — and serving the empty list is no better,
+        // because "no runs are `faild`" and "no runs failed" read identically to
+        // a caller who cannot see their own typo. Both are a monitoring surface
+        // answering "you have no failures" with confidence.
+        const { details, status, listRuns } = await refusalFor({ status: raw });
+
+        expect(details?.code).toBe('VALIDATION_FAILED');
+        expect(status).toBe(400);
+        // ADR-0114's closed catalog already carries the constraint this
+        // violates — `invalid_option`, "not a member of the field's declared
+        // options". No new error vocabulary is minted for it.
+        expect(details?.fields).toEqual([
+            { field: 'status', code: 'invalid_option', message: expect.stringContaining('`status`') },
+        ]);
+        expect(listRuns).not.toHaveBeenCalled();
+    });
+
+    it.each([
+        ['repeated parameter', ['failed', 'completed']],
+        ['structured', { $ne: 'failed' }],
+        ['numeric', 7],
+    ])('refuses ?status=%s — it was never a single string (invalid_type)', async (_label, raw) => {
+        // The same mapping `parseStringParam` makes for the same condition: a
+        // repeated `?status=failed&status=completed` arrives as an ARRAY, and a
+        // filter is not a set on this wire. `String([...])` would have made it
+        // the single value `'failed,completed'`, matching nothing.
+        const { details, status, listRuns } = await refusalFor({ status: raw });
+
+        expect(details?.code).toBe('VALIDATION_FAILED');
+        expect(status).toBe(400);
+        expect(details?.fields).toEqual([
+            { field: 'status', code: 'invalid_type', message: expect.stringContaining('`status`') },
+        ]);
+        expect(listRuns).not.toHaveBeenCalled();
+    });
+
+    it('names the declared members in the message, and caps the echoed value', async () => {
+        const { message } = await refusalFor({ status: 'z'.repeat(500) });
+
+        expect(message).toContain('failed');   // the caller is told what IS accepted
+        expect(message).toContain('pending');
+        expect(message.length).toBeLessThan(300);
+    });
+});
+
 describe('#7300 — every value that had a defensible answer keeps it', () => {
     async function listWith(query: Record<string, unknown> | undefined) {
         const { dispatcher, listRuns } = makeDispatcher();
@@ -141,28 +206,28 @@ describe('#7300 — every value that had a defensible answer keeps it', () => {
 
     it.each([
         // [label, query, the exact options object `listRuns` must receive]
-        ['?limit=20', { limit: '20' }, { limit: 20, cursor: undefined }],
-        ['?limit=1 (the low boundary)', { limit: '1' }, { limit: 1, cursor: undefined }],
-        ['?limit=100 (the declared high boundary)', { limit: '100' }, { limit: 100, cursor: undefined }],
+        ['?limit=20', { limit: '20' }, { limit: 20, cursor: undefined, status: undefined }],
+        ['?limit=1 (the low boundary)', { limit: '1' }, { limit: 1, cursor: undefined, status: undefined }],
+        ['?limit=100 (the declared high boundary)', { limit: '100' }, { limit: 100, cursor: undefined, status: undefined }],
         // Out of RANGE is not out of DOMAIN. `ListRunsRequestSchema` bounds
         // `limit` to 1..100 and the engine slices by whatever it is handed;
         // neither answer is this boundary's to change, so both still arrive.
-        ['?limit=1000 (over the declared range)', { limit: '1000' }, { limit: 1000, cursor: undefined }],
-        ['?limit=-5 (under it)', { limit: '-5' }, { limit: -5, cursor: undefined }],
+        ['?limit=1000 (over the declared range)', { limit: '1000' }, { limit: 1000, cursor: undefined, status: undefined }],
+        ['?limit=-5 (under it)', { limit: '-5' }, { limit: -5, cursor: undefined, status: undefined }],
         // Falsy spellings meant "no limit here" before this gate existed and
         // still do — they must not become a new 400. `'0'` is NOT one of them:
         // the string is truthy, so `query.limit ? Number(query.limit) : …` read
         // it as the number `0` and passed it on, and that is preserved too.
-        ['?limit= (empty)', { limit: '' }, { limit: undefined, cursor: undefined }],
-        ['?limit=0', { limit: '0' }, { limit: 0, cursor: undefined }],
-        ['limit: 0 (in-process number)', { limit: 0 }, { limit: undefined, cursor: undefined }],
-        ['limit: null', { limit: null }, { limit: undefined, cursor: undefined }],
-        ['no parameters at all', {}, { limit: undefined, cursor: undefined }],
+        ['?limit= (empty)', { limit: '' }, { limit: undefined, cursor: undefined, status: undefined }],
+        ['?limit=0', { limit: '0' }, { limit: 0, cursor: undefined, status: undefined }],
+        ['limit: 0 (in-process number)', { limit: 0 }, { limit: undefined, cursor: undefined, status: undefined }],
+        ['limit: null', { limit: null }, { limit: undefined, cursor: undefined, status: undefined }],
+        ['no parameters at all', {}, { limit: undefined, cursor: undefined, status: undefined }],
         // A cursor is opaque: every string passes through VERBATIM, including
         // the empty one, exactly as the raw passthrough did.
-        ['?cursor=n_007', { cursor: 'n_007' }, { limit: undefined, cursor: 'n_007' }],
-        ['?cursor= (empty)', { cursor: '' }, { limit: undefined, cursor: '' }],
-        ['both together', { limit: '5', cursor: 'n_007' }, { limit: 5, cursor: 'n_007' }],
+        ['?cursor=n_007', { cursor: 'n_007' }, { limit: undefined, cursor: 'n_007', status: undefined }],
+        ['?cursor= (empty)', { cursor: '' }, { limit: undefined, cursor: '', status: undefined }],
+        ['both together', { limit: '5', cursor: 'n_007' }, { limit: 5, cursor: 'n_007', status: undefined }],
     ])('%s answers 200 and reaches the service unchanged', async (_label, query, expected) => {
         const { result, listRuns } = await listWith(query);
 
@@ -180,15 +245,52 @@ describe('#7300 — every value that had a defensible answer keeps it', () => {
         expect(listRuns).toHaveBeenCalledWith('welcome_flow', undefined);
     });
 
-    it('leaves an unknown query key alone — `?status=failed` is ignored, not refused (#6361)', async () => {
-        // `ListRunsRequestSchema` declares a `status` filter that this handler
-        // has never read, so the key is silently ignored today. Refusing unknown
-        // keys — or starting to honour this one — is a separate decision with
-        // its own blast radius; this change takes neither.
+    // ── #7359 ────────────────────────────────────────────────────────────────
+    // The block above used to end with a case asserting that `?status=failed`
+    // was IGNORED — #7300 deliberately preserved that, since choosing between
+    // honouring and retiring the declared key was a separate decision. #7359
+    // took the enforce route, so that pin is superseded rather than deleted:
+    // the cases below assert the opposite behaviour on the same input.
+
+    it('FORWARDS a declared `?status=` to the service instead of dropping it', async () => {
+        // The defect: `status` is declared by `ListRunsRequestSchema` but was
+        // never built into this handler's option object, so it never left the
+        // HTTP layer. The caller got 200 + every run of the flow — a caller
+        // paging for failures read the first `limit` runs of ANY status and
+        // concluded those were the failures.
         const { result, listRuns } = await listWith({ limit: '2', status: 'failed' });
 
         expect(result.response?.status).toBe(200);
-        expect(listRuns).toHaveBeenCalledWith('welcome_flow', { limit: 2, cursor: undefined });
+        expect(listRuns).toHaveBeenCalledWith('welcome_flow', { limit: 2, cursor: undefined, status: 'failed' });
+    });
+
+    it.each(
+        ['pending', 'running', 'paused', 'completed', 'failed', 'cancelled', 'timed_out', 'retrying'],
+    )('forwards every declared ExecutionStatus member — ?status=%s', async (member) => {
+        // The gate reads its members from the spec's `ExecutionStatus` enum, the
+        // same one `ListRunsRequestSchema` is built from, so this pins that the
+        // wire's declared set and the boundary's accepted set are one set. A
+        // member added to the enum and refused here would fail this row.
+        const { result, listRuns } = await listWith({ status: member });
+
+        expect(result.response?.status).toBe(200);
+        expect(listRuns).toHaveBeenCalledWith('welcome_flow', { limit: undefined, cursor: undefined, status: member });
+    });
+
+    it.each([
+        ['absent', {}],
+        ['?status= (empty — an "All statuses" select)', { status: '' }],
+        ['status: null', { status: null }],
+    ])('%s still means NO filter — the unnarrowed listing is unchanged', async (_label, query) => {
+        // The preservation half. An absent filter must keep reaching the
+        // service as `undefined` (list everything), and the empty spelling must
+        // not become a new 400: unlike `?read=`, which used to serve the wrong
+        // HALF of the inbox, `?status=` already served exactly what "no filter"
+        // means, so it had a defensible answer to preserve.
+        const { result, listRuns } = await listWith(query);
+
+        expect(result.response?.status).toBe(200);
+        expect(listRuns).toHaveBeenCalledWith('welcome_flow', expect.objectContaining({ status: undefined }));
     });
 
     it('still refuses an anonymous caller with 401 before it ever looks at the query', async () => {