docs(client): narrow the limit-refusal sentence to what the guard does; re-point the card

FAIL ground: 'a value outside that range is REFUSED' was false at exactly the
falsy inputs. automation.runs.list guards on truthiness, so { limit: 0 } and
NaN are dropped client-side and the server answers its default window; the two
listRuns surfaces guard on != null and do send them. Proven by executing all
three emitters against eight edge inputs, not by reading. Option (b): the
guard is pre-existing and unauthorized to change, so the sentence narrows to
what the code does rather than the code changing to fit the sentence.

Same stroke: 'read by nothing on the server' becomes 'validated at the
boundary and read by nothing beyond it', matching the prescription — the
boundary did read the key, to validate it.

Card rebuild: #19365 is permanently 404 and #19543 replaces it. All 41
citations in this diff re-pointed (39 hand-written, 2 regenerated into the
registry mirror). #6361 is untouched at 13 occurrences — still 404, not among
the gate's sites, and not reconstructable.

Claude-Session: https://claude.ai/code/session_01UDXER3sdqfeVYpEWZs5mZx
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/19365-automation-runs-cursor-hasmore.md

@@ -5,7 +5,7 @@
 '@objectstack/client': minor
 ---
 
-feat(automation): `GET /automation/:name/runs` retires `cursor` and computes `hasMore` (#19365)
+feat(automation): `GET /automation/:name/runs` retires `cursor` and computes `hasMore` (#19543)
 
 This door declared a pagination parameter it never spent and then reported, as a
 literal, that there was nothing more to fetch. Both halves are closed here, per

content/docs/automation/flows.mdx

@@ -1842,7 +1842,7 @@ curl -b cookies.txt -X POST \
 | Endpoint | Purpose |
 |:---|:---|
 | `POST /api/v1/automation/:name/trigger` | Start a flow (canonical) |
-| `GET /api/v1/automation/:name/runs` | List runs (`?limit` — 1–100, default 20, the window and the only way to ask for more; `?status` — narrow to one execution status; an undeclared value is refused `400 VALIDATION_FAILED`). `?cursor` was **removed in `@objectstack/spec` 17.5** (#19365): this door mints no continuation token, so a request still carrying it is ignored rather than refused — it used to answer `400 VALIDATION_FAILED` when repeated. The response `hasMore` is computed from the engine's truncation report rather than the constant `false` it used to be, so widen `?limit` when it is `true` — with `?status=`, a `false` means no further match inside the scanned window rather than none at all, because the window is taken before the filter is applied. `501 NOT_IMPLEMENTED` when the service does not declare `listRunsPage`. Requires read on `sys_automation_run` — see [Observing runs](#observing-runs) |
+| `GET /api/v1/automation/:name/runs` | List runs (`?limit` — 1–100, default 20, the window and the only way to ask for more; `?status` — narrow to one execution status; an undeclared value is refused `400 VALIDATION_FAILED`). `?cursor` was **removed in `@objectstack/spec` 17.5** (#19543): this door mints no continuation token, so a request still carrying it is ignored rather than refused — it used to answer `400 VALIDATION_FAILED` when repeated. The response `hasMore` is computed from the engine's truncation report rather than the constant `false` it used to be, so widen `?limit` when it is `true` — with `?status=`, a `false` means no further match inside the scanned window rather than none at all, because the window is taken before the filter is applied. `501 NOT_IMPLEMENTED` when the service does not declare `listRunsPage`. Requires read on `sys_automation_run` — see [Observing runs](#observing-runs) |
 | `GET /api/v1/automation/:name/runs/:runId` | One run's detail (404 `Execution not found`). Requires read on `sys_automation_run` — see [Observing runs](#observing-runs) |
 | `POST /api/v1/automation/:name/runs/:runId/resume` | Resume a paused run — body `{ inputs, output, branchLabel }` |
 | `GET /api/v1/automation/:name/runs/:runId/screen` | The pending screen of a screen-flow run |

packages/client/src/client.test.ts

@@ -1433,21 +1433,21 @@ describe('ObjectStackClient.automation', () => {
 
         // `limit` is the whole query surface of this door now. It used to be
         // pinned here alongside `cursor=abc`; that half moved to the absence
-        // pin below when #19365 retired the key.
+        // pin below when #19543 retired the key.
         await client.automation.runs.list('my_flow', { limit: 5 });
         expect(fetchMock).toHaveBeenCalledWith(
             'http://localhost:3000/api/v1/automation/my_flow/runs?limit=5',
             expect.any(Object),
         );
     });
 
-    it('[#19365] never puts a `cursor` on the query string — on ANY of the three run-list surfaces', async () => {
+    it('[#19543] never puts a `cursor` on the query string — on ANY of the three run-list surfaces', async () => {
         // This test used to assert the OPPOSITE — it pinned the URL
         // `…/runs?limit=5&cursor=abc`, i.e. that the SDK produced the key. That
         // is what made the parameter harmful rather than inert: `cursor` was
         // accepted at the boundary and read by nothing, so a caller paginating
         // by the published contract re-read the first window forever with no
-        // error. #19365 retires it, and the assertion inverts on the same input.
+        // error. #19543 retires it, and the assertion inverts on the same input.
         //
         // The type surface is the enforced channel — `list({ cursor })` is a
         // TS2353 excess-property error, which a runtime assertion cannot reach.

packages/client/src/index.ts

@@ -5538,15 +5538,24 @@ export class ObjectStackClient {
            *
            * Returns the newest `limit` runs — a WINDOW, not a page. The
            * `cursor` parameter was removed in `@objectstack/spec` 17.5.0
-           * (#19365): it was appended to the query string here and read by
-           * nothing on the server, so a caller paginating by it re-read the
-           * first window forever.
+           * (#19543): it was appended to the query string here, validated at
+           * the boundary and read by nothing beyond it, so a caller
+           * paginating by it re-read the first window forever.
            *
-           * Omit `limit` to take the server's window (20). It is
-           * bounded to 1..100 and a value outside that range is REFUSED with
-           * `400 VALIDATION_FAILED`, never clamped — so raise it deliberately
-           * to see further back. There is no continuation token — read
-           * `hasMore` to learn whether the window was short.
+           * Omit `limit` to take the server's window (20). The declared range
+           * is 1..100, and a value this method SENDS that falls outside it is
+           * REFUSED with `400 VALIDATION_FAILED`, never clamped — so raise it
+           * deliberately to see further back.
+           *
+           * ⚠️ `0` and `NaN` are the exception, and they are dropped rather
+           * than refused: the guard below is truthy, so a falsy `limit` never
+           * leaves the client and the server answers its DEFAULT window
+           * instead. `-5`, `1.5` and `101` are truthy, are sent, and are
+           * refused. The two `listRuns` surfaces guard on `!= null` and do
+           * send `0`.
+           *
+           * There is no continuation token — read `hasMore` to learn whether
+           * the window was short.
            */
           list: async (flowName: string, options?: { limit?: number }): Promise<{ runs: ExecutionLog[]; hasMore: boolean }> => {
               const route = this.getRoute('automation');
@@ -5620,7 +5629,7 @@ export class ObjectStackClient {
       /**
        * Alias for `automation.runs.list`.
        *
-       * `cursor` was removed in `@objectstack/spec` 17.5.0 (#19365) — see that
+       * `cursor` was removed in `@objectstack/spec` 17.5.0 (#19543) — see that
        * method for the reason. A window, not a page: widen `limit`
        * (1..100, default 20) and read `hasMore`.
        */
@@ -8105,7 +8114,7 @@ export class ScopedEnvironmentClient {
     /**
      * List recent runs for a flow, optionally narrowed to one status.
      *
-     * `cursor` was removed in `@objectstack/spec` 17.5.0 (#19365) — see
+     * `cursor` was removed in `@objectstack/spec` 17.5.0 (#19543) — see
      * `automation.runs.list` for the reason. A window, not a page: widen
      * `limit` (1..100, default 20) and read `hasMore`.
      */

packages/runtime/src/domains/automation-run-read-permission-gate.test.ts

@@ -94,7 +94,7 @@ function makeDispatcher(
 ): Harness {
     const explainCalls: ExplainCall[] = [];
     const getRun = vi.fn(async () => PAUSED_RUN as unknown);
-    // [#19365] The door reads the PAGE member — `listRuns` alone cannot
+    // [#19543] The door reads the PAGE member — `listRuns` alone cannot
     // report truncation, so a door that has to answer `hasMore` calls this
     // one. The gate under test is unaffected either way: it refuses ahead of
     // the service probe, deliberately, so that a 501-vs-403 is not what tells

packages/runtime/src/domains/automation-runs-query-validation.test.ts

@@ -68,7 +68,7 @@ import { validationFailureDetails, VALIDATION_FAILED_STATUS } from '../validatio
  * An automation slot whose `listRunsPage` records exactly what it was asked
  * for.
  *
- * [#19365] The double serves `listRunsPage` — the page-shaped member the door
+ * [#19543] The double serves `listRunsPage` — the page-shaped member the door
  * now calls — rather than `listRuns`. The recorded OPTIONS object is what
  * every preservation row below pins, and it is unchanged by that switch except
  * for the retired `cursor` key: the door still forwards the caller's own
@@ -157,7 +157,7 @@ describe('#7300 — GET /automation/:name/runs refuses a malformed `limit` inste
     });
 });
 
-describe('#19365 — `cursor` is RETIRED, so this boundary stops reading it', () => {
+describe('#19543 — `cursor` is RETIRED, so this boundary stops reading it', () => {
     // ⚠️ This block SUPERSEDES #7300's cursor refusal cases rather than
     // extending them, and the supersession is a deliberate reversal, not a
     // relaxation that slipped through. #7300 refused `?cursor=a&cursor=b` with
@@ -209,7 +209,7 @@ describe('#19365 — `cursor` is RETIRED, so this boundary stops reading it', ()
     });
 });
 
-describe('#19365 — `hasMore` is RELAYED from the service, never a constant', () => {
+describe('#19543 — `hasMore` is RELAYED from the service, never a constant', () => {
     // The defect this closes, in the source's own words: the door returned
     // `deps.success({ runs, hasMore: false })` — a literal — beside a list the
     // engine had already cut with `.slice(0, limit)`. A caller asking for one
@@ -401,7 +401,7 @@ describe('#7300 — every value that had a defensible answer keeps it', () => {
         ['no parameters at all', {}, { limit: undefined, status: undefined }],
         // The three `?cursor=` preservation rows that stood here — a verbatim
         // string, the empty spelling, and `limit` + `cursor` together — are
-        // superseded by the `#19365` block above rather than deleted outright:
+        // superseded by the `#19543` block above rather than deleted outright:
         // the key is retired, so "reaches the service unchanged" is no longer
         // the behaviour to preserve. What replaced them asserts the opposite
         // on the same inputs, which is the same supersession shape #7359 and

packages/runtime/src/domains/automation.ts

@@ -1539,7 +1539,7 @@ async function consumedSuspensionSurvives(
  *   GET    /:name/runs           → listRunsPage (query: limit — validated AND
  *                                  honoured end to end, #7300 / #8054; status —
  *                                  validated AND honoured, #7359; cursor —
- *                                  RETIRED, #19365, so a value carrying it is
+ *                                  RETIRED, #19543, so a value carrying it is
  *                                  ignored rather than validated). `hasMore` is
  *                                  computed from the engine's own truncation
  *                                  report, never a constant. A service without
@@ -2571,7 +2571,7 @@ export async function handleAutomationRequest(deps: DomainHandlerDeps, path: str
                 //    first implementation that starts honouring cursors must not
                 //    be the one that discovers the type was never enforced.
                 //
-                // [#19365] ⚠️ THAT SECOND BULLET IS NOW HISTORY, AND ITS
+                // [#19543] ⚠️ THAT SECOND BULLET IS NOW HISTORY, AND ITS
                 // DECISION IS REVERSED ON PURPOSE. #7300 chose to validate a
                 // key rather than decide it, on the reasoning that a future
                 // cursor implementation must not be the one to discover the
@@ -2662,7 +2662,7 @@ export async function handleAutomationRequest(deps: DomainHandlerDeps, path: str
                 const { runs, hasMore } = await automationService.listRunsPage(name, options);
                 return { handled: true, response: deps.success({ runs, hasMore }) };
             }
-            // [#19365] A service that does not implement `listRunsPage` is told
+            // [#19543] A service that does not implement `listRunsPage` is told
             // so, and ⛔ never answered 200 with an invented `hasMore`. Falling
             // through to the domain's 404 would have been the silent form: the
             // caller cannot tell "this deployment mounts no run listing" from

packages/runtime/src/http-dispatcher.test.ts

@@ -297,7 +297,7 @@ describe('HttpDispatcher', () => {
                 execute: vi.fn().mockResolvedValue({ success: true, output: {} }),
                 toggleFlow: vi.fn().mockResolvedValue(undefined),
                 listRuns: vi.fn().mockResolvedValue([{ id: 'run_1', status: 'completed' }]),
-                // [#19365] The run-list door calls the PAGE member; `listRuns`
+                // [#19543] The run-list door calls the PAGE member; `listRuns`
                 // stays declared here because the CONTRACT still declares it,
                 // and this mock's subject is contract completeness (#4127).
                 listRunsPage: vi.fn().mockResolvedValue({

packages/services/service-automation/src/engine.ts

@@ -4568,7 +4568,7 @@ export class AutomationEngine implements IAutomationService {
         flowName: string,
         options?: { limit?: number; status?: ExecutionStatus },
     ): Promise<ExecutionLogEntry[]> {
-        // [#19365] ONE implementation, two projections — `listRunsPage` is the
+        // [#19543] ONE implementation, two projections — `listRunsPage` is the
         // whole method and this is its `runs` half. ⛔ Never re-derive the
         // listing here: a second copy of the merge/filter/sort would be the
         // fork the route-ownership rule refuses, and it is the half that would
@@ -4577,7 +4577,7 @@ export class AutomationEngine implements IAutomationService {
     }
 
     /**
-     * [#19365] The run listing AND whether it was truncated — the member the
+     * [#19543] The run listing AND whether it was truncated — the member the
      * REST door builds `hasMore` from.
      *
      * ## What "truncated" means at this seam, and why `runs.length === limit` is not it
@@ -4701,7 +4701,7 @@ export class AutomationEngine implements IAutomationService {
         let durable: ExecutionLogEntry[] = [];
         if (this.store?.listHistory) {
             try {
-                // [#19365] `limit + 1`, not `limit` — the over-read that makes
+                // [#19543] `limit + 1`, not `limit` — the over-read that makes
                 // `hasMore` answerable at all. Asking for exactly `limit` makes a
                 // saturated window and a complete one identical; one extra row
                 // tells them apart, and `.slice(0, limit)` below drops it again
@@ -4795,7 +4795,7 @@ export class AutomationEngine implements IAutomationService {
             : [...byId.values()].filter(e => e.status === status);
         const ordered = merged
             .sort((a, b) => (b.startedAt ?? '').localeCompare(a.startedAt ?? ''));
-        // [#19365] The comparison is against the ORDERED, FILTERED set, not
+        // [#19543] The comparison is against the ORDERED, FILTERED set, not
         // against what any single source returned: a row can reach `ordered`
         // from the ring or the paused arm without the history arm knowing, and
         // a `?status=` filter can drop the over-read row specifically. Reading

packages/services/service-automation/src/run-list-truncation.test.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * #19365 — `AutomationEngine.listRunsPage` and the truncation boundary.
+ * #19543 — `AutomationEngine.listRunsPage` and the truncation boundary.
  *
  * `GET /api/automation/:name/runs` used to answer `{ runs, hasMore: false }`
  * with the `false` written as a literal, beside a list the engine had already
@@ -83,7 +83,7 @@ async function pageOf(count: number, limit: number) {
     return engine.listRunsPage(FLOW, { limit });
 }
 
-describe('#19365 — hasMore at the truncation boundary', () => {
+describe('#19543 — hasMore at the truncation boundary', () => {
     it.each([
         ['far fewer than the window', 3, 10, false, 3],
         ['one short of the window', 9, 10, false, 9],
@@ -117,7 +117,7 @@ describe('#19365 — hasMore at the truncation boundary', () => {
 
     it('asks the STORE for `limit + 1` — the over-read is where the fact comes from', async () => {
         // The mechanism pin. `RunStore.listHistory`'s signature is deliberately
-        // unchanged (#19365): over-reading is expressible in the `limit` it
+        // unchanged (#19543): over-reading is expressible in the `limit` it
         // already takes, so the truncation signal costs the store contract
         // nothing. A regression to `listHistory(flow, limit)` would make the
         // EXACTLY-the-window case above indistinguishable from the one above
@@ -179,7 +179,7 @@ describe('#19365 — hasMore at the truncation boundary', () => {
     });
 });
 
-describe('#19365 — `listRuns` is the `runs` half of the same call', () => {
+describe('#19543 — `listRuns` is the `runs` half of the same call', () => {
     it('returns the identical window, and reports no truncation of its own', async () => {
         // ONE implementation, two projections. A second merge/filter/sort here
         // would be the fork the route-ownership rule refuses, and it is the