proteum 2.5.16 → 2.5.18

package/agents/project/AGENTS.md

@@ -23,6 +23,7 @@ Managed compact root routers must use trigger -> canonical instruction file refe
 - For every non-trivial coding task, load and follow root-level `DOCUMENTATION.md` before coding.
 - For bug fixes, regressions, incidents, broken public routes, auth/OAuth failures, integration failures, or production behavior fixes, load and follow root-level `DOCUMENTATION.md` before coding so the relevant fix note, regression-test docs, ADR, or explicit skip reason is handled in the same change.
 - If the user reports an issue, or you encounter one during exploration, implementation, verification, or runtime reproduction, load and follow root-level `diagnostics.md`.
+- If the task adds or changes client data fetching, polling, or retry behavior, read the `Client Request Discipline` section in `client/AGENTS.md` before editing.
 - If the task touches client-side files, especially `client/**` and page files, load and apply root-level `optimizations.md` only after implementation for post-implementation checking and optimization. Skip it at task start and skip it for server-only, test-only, doc-only, and non-client refactor tasks unless the user explicitly asks for optimization work.
 - If the task changes UX, copy, onboarding, pricing, product semantics, or commercial positioning, use root-level `DOCUMENTATION.md` to choose the smallest relevant `./docs/` pack before editing. If a dev server is already running, print the live dev server URL as a clickable Markdown link.
 - If the task needs new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.

package/agents/project/client/AGENTS.md

@@ -31,6 +31,17 @@ Coding style source of truth: root-level `CODING_STYLE.md`.
 - Toasts and form errors are local feedback only; use `setError(context.app.handleError(error, fallbackMessage))` or rethrow the caught error.
 - `console.*(error)` is not error handling and must not be the last stop for a caught error.
 
+## Client Request Discipline
+
+- A page or layout must not accumulate one mount-time API call per component or store. Before adding a request that fires on page load, extend an existing load-time payload (SSR `data`, the surface's bootstrap endpoint, or an already-fetched store) and hydrate from it; a new load-time call requires an explicit reason why no existing read can carry the data.
+- When an endpoint accepts a set (for example an array of ids), request the whole needed set in one call and coalesce triggers that land in the same tick. Never loop single-item requests over a known set.
+- Any effect or reactive block that can issue a request must key on explicit values (ids, tokens, statuses), must guard with sequence tokens so state identity churn cannot re-fire it, and must treat every terminal status, including `'error'`, as ineligible for automatic re-request.
+- Automatic retries require exponential backoff with jitter, a hard attempt cap, and respect for server pacing (`retryAfterMs`, `Retry-After`). A transport failure or a server failed status ends in a terminal error state with a manual retry affordance, never in an immediate re-request from a render or effect cycle.
+- Treat HTTP 429 as a stop signal for the whole surface, not as a retriable error.
+- Long polls honor the server-provided delay, run as a single chain per logical resource, and are cancelled when superseded or unmounted.
+- Identical concurrent requests must share one in-flight promise, usually a module-level cache with in-flight dedupe.
+- After changing load-time fetching, polling, or retry behavior, measure the surface's executed request count (browser network log or a request-count contract test) and report the before and after numbers with the change.
+
 ## Design
 
 - Follow the existing design language of the touched area.

package/eslint.js

@@ -183,6 +183,8 @@ const hasOptionalCallBoundary = (callExpression, ancestors = []) => {
     return hasOptional || ancestors.some(({ node }) => node.type === 'ChainExpression');
 };
 
+// A loop body is iteration, not a condition. `for (const item of batch) item.reject(error)`
+// preserves the error for every item there is, so it is not a swallow.
 const isUnderConditionalControlFlow = (ancestors = []) =>
     ancestors.some(({ node, childKey }) => {
         if (node.type === 'IfStatement') return childKey === 'consequent' || childKey === 'alternate';
@@ -190,13 +192,33 @@ const isUnderConditionalControlFlow = (ancestors = []) =>
         if (node.type === 'LogicalExpression') return childKey === 'right';
         if (node.type === 'SwitchCase') return childKey === 'consequent';
 
-        return (
-            ['ForInStatement', 'ForOfStatement', 'ForStatement', 'WhileStatement', 'DoWhileStatement'].includes(
-                node.type,
-            ) && childKey === 'body'
-        );
+        return false;
     });
 
+/**
+ * Does the handler throw, whatever it throws?
+ *
+ * `catch { throw new Error('must be an absolute URL') }` translates a failure
+ * into the domain's own vocabulary. The original object is dropped, but the
+ * failure still propagates and nothing continues silently, which is what this
+ * rule exists to prevent. Attaching the original as `cause` is better practice,
+ * not a separate correctness question for this rule.
+ */
+const handlerThrows = (node) => {
+    let throws = false;
+
+    traverseNode(node, (child, _parent, _parentKey, ancestors) => {
+        if (child.type === 'ThrowStatement' && !isUnderConditionalControlFlow(ancestors)) throws = true;
+    });
+
+    return throws;
+};
+
+// A returned fallback is deliberately NOT accepted. `catch { return null }` is
+// the textbook swallow, and no structural signal separates it from
+// `.catch(() => [])`. Where a fallback really is correct, the call site says so
+// with a disable comment and a reason, which stays greppable.
+
 const defaultErrorReporters = ['app.reportError', 'app.handleError'];
 
 /**
@@ -363,6 +385,11 @@ const createSwallowedErrorRule = () => ({
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
+                // Nothing was bound, so nothing can be routed. Still accepted when
+                // the handler translates the failure into a throw, because the
+                // failure keeps propagating rather than being continued past.
+                if (handlerThrows(body)) return;
+
                 context.report({ node, messageId: 'missingParam' });
                 return;
             }
@@ -373,6 +400,8 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
+            if (handlerThrows(body)) return;
+
             if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side, reporters)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.16",
+	"version": "2.5.18",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/tests/error-boundary-rules.test.cjs

@@ -240,6 +240,46 @@ test('an error pushed into a result collection counts as preservation', () => {
     assert.equal(count(messages, swallowedRuleId), 0);
 });
 
+test('translating a failure into a new throw counts, even without the original', () => {
+    const messages = lint(`
+        export const assertUrl = (raw) => {
+            try {
+                return new URL(raw);
+            } catch {
+                throw new Error('must be an absolute URL');
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('preservation inside a loop body counts, because iteration is not a condition', () => {
+    const messages = lint(`
+        export const run = (batch) => {
+            load().catch((error) => {
+                for (const item of batch) {
+                    item.reject(error);
+                }
+            });
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a returned fallback is still a swallow, however it is spelled', () => {
+    const nullFallback = lint(`
+        export const run = () => {
+            try { risky(); } catch { return null; }
+        };
+    `);
+    assert.equal(count(nullFallback, swallowedRuleId), 1);
+
+    const emptyList = lint(`export const run = (d) => dns.resolveMx(d).catch(() => []);`);
+    assert.equal(count(emptyList, swallowedRuleId), 1);
+});
+
 test('a console-only catch is still reported', () => {
     const messages = lint(`
         export const run = async () => {