proteum 2.5.13 → 2.5.15

package/agents/project/CODING_STYLE.md

@@ -85,6 +85,8 @@ Write anchors in a leading block comment:
 
 - `@docs` points at the feature pack that owns the file. Required on every file that default-exports `definePageRoute`, `defineController`, `defineServerRoute`, or `defineServerRoutes`, and on every exported class extending a service base such as `Service` or `UsersManagementService`. Error routes are exempt: they render a status message and carry no feature-specific rule, so requiring a pack for one would manufacture documentation. Add an anchor to an error route only when it really does carry a rule.
 - Components are not covered automatically. A presentational primitive such as `Icon.tsx` or `Card.tsx` owns no feature, so a blanket rule would manufacture documentation for hundreds of files. Cover the component directories that do own a feature by listing them in `includeDocAnchors` when building the ESLint config, for example `['client/components/paywall/**']`.
+- Infrastructure is exempt the same way error routes are. A transport helper, a metrics router or a rate limiter owns no feature contract, so list those paths in `excludeDocAnchors` rather than pointing them at a pack that does not describe them. An excluded file may still declare anchors, and `valid-doc-anchor` keeps checking any it declares.
+- A feature pack that no code will ever point at, such as a retirement record or a document describing audiences rather than modules, opts out of the orphan report by carrying a `RETIRED` note or a `code-owned: false` line in its README. Without that, the pack is reported as orphaned forever and the backlog stops being actionable.
 - `@adr` and `@fix` point at the decision record and fix note that constrain the file. Add them where the decision or the bug actually lives, not on every file in the area.
 - `@rule` states the invariant inline, in full. It is the one anchor that carries content rather than a pointer, because the rule is what an agent needs at the moment of editing. A `@rule` that only says `todo` or repeats the linked title is a defect.
 - Anchors are not a substitute for the documents. Narrative, alternatives, benchmarks and acceptance stay under `docs/**`; the anchor carries the pointer and the single-sentence rule.
@@ -95,6 +97,27 @@ The read-only MCP owner payloads return these anchors alongside `explain_summary
 
 `proteum docs check` verifies the whole corpus in both directions: it fails on an anchor that no longer resolves, and reports as a backlog every fix note carrying an `Agent warning` that no code anchors, plus every feature pack nothing points at. `proteum verify changed` selects it automatically whenever `docs/**` or a source file changes, so a renamed document cannot silently orphan an anchor.
 
+## Trust boundaries and caught errors
+
+Two rules police the edges of the type system and the error path. Both allow the correct idiom and report the lazy one, so read the message before reaching for a disable comment.
+
+`proteum/no-loose-unknown` reports `unknown` because it usually hides a contract that should be written down. It allows `unknown` in three places, because there it is the correct and safe answer:
+
+- a catch binding, which is how TypeScript types it;
+- the input of a type guard, since narrowing an untrusted value is the guard's whole job;
+- anything carrying a `@boundary` tag in its doc comment.
+
+Use `@boundary` when the value genuinely arrives from outside: a parsed response, a provider payload, a third-party shim. State where it comes from, so the codebase's trust boundaries stay greppable:
+
+```typescript
+/** @boundary HumbleWorth prediction output, shape owned by the provider. */
+export const parseOutput = (output: unknown) => ...
+```
+
+`proteum/no-swallowed-caught-error` requires a caught error to reach somewhere. It accepts a rethrow, `Promise.reject`, `next(error)` for Express propagation, an error surfaced to the caller as a returned or pushed result, and the reporters configured through `errorReporters`. It also accepts preservation guarded by a condition **about the error**, because choosing which failures to report is a decision. It still reports a guard on whether the reporter exists, such as `if (app) app.reportError(error)`, because the error is lost whenever it does not.
+
+`console.error(error)` is not error handling and never satisfies either rule.
+
 ## Self-check before finishing
 
 Re-scan every touched file against this list before declaring the work done:

package/cli/commands/docs.ts

@@ -130,6 +130,25 @@ const resolveAdrReference = (value: string, fromDirectory: string, root: string)
     );
 };
 
+const retiredPackPattern = /^\s*>?\s*RETIRED\b/im;
+const notCodeOwnedPattern = /^\s*>?\s*code-owned:\s*false\s*$/im;
+
+/**
+ * A pack opts out of the orphan report by saying so in its README, either with
+ * a `RETIRED` note or a `code-owned: false` line.
+ *
+ * Retirement records and intent documents describe decisions and audiences, not
+ * modules, so no source file will ever point at them. Reporting those forever
+ * trains a reader to ignore the whole list.
+ */
+const packOptsOutOfOrphanReport = (featuresDir: string, pack: string) => {
+    const readme = path.join(featuresDir, pack, 'README.md');
+    if (!fs.existsSync(readme)) return false;
+
+    const content = fs.readFileSync(readme, 'utf8');
+    return retiredPackPattern.test(content) || notCodeOwnedPattern.test(content);
+};
+
 const listFeaturePacks = (root: string) => {
     const featuresDir = path.join(root, 'docs', 'features');
     if (!fs.existsSync(featuresDir)) return [];
@@ -137,6 +156,7 @@ const listFeaturePacks = (root: string) => {
     return fs
         .readdirSync(featuresDir, { withFileTypes: true })
         .filter((entry) => entry.isDirectory())
+        .filter((entry) => !packOptsOutOfOrphanReport(featuresDir, entry.name))
         .map((entry) => entry.name);
 };
 

package/eslint.js

@@ -197,32 +197,131 @@ const isUnderConditionalControlFlow = (ancestors = []) =>
         );
     });
 
-const isPreservingCall = (callExpression, names, side, ancestors = []) => {
+const defaultErrorReporters = ['app.reportError', 'app.handleError'];
+
+/**
+ * Does this call match one of the configured `receiver.method` reporters?
+ *
+ * The receiver may be a bare identifier or the property of a longer chain, so
+ * `app.reportError(...)`, `this.app.reportError(...)` and `ctx.app.report(...)`
+ * all match a `app.reportError` entry.
+ */
+const matchesConfiguredReporter = (callExpression, reporters) => {
+    const method = getMemberPropertyName(callExpression.callee);
+    if (!method) return false;
+
+    // Only project-added reporters are matched here. The built-in two stay with
+    // the side logic below, so a server file calling the client's `handleError`
+    // is still reported rather than quietly accepted.
+    const extraReporters = reporters.filter((reporter) => !defaultErrorReporters.includes(reporter));
+
+    return extraReporters.some((reporter) => {
+        const [receiverName, methodName] = reporter.includes('.') ? reporter.split('.') : [null, reporter];
+        if (method !== methodName) return false;
+        if (receiverName === null) return true;
+
+        const receiver = callExpression.callee.object;
+        if (receiver?.type === 'Identifier') return receiver.name === receiverName;
+
+        return getMemberPropertyName(receiver) === receiverName;
+    });
+};
+
+/**
+ * Express hands a caught error to its error middleware with `next(error)`. That
+ * is the framework's own propagation path, so treating it as a swallow would
+ * report the correct implementation of every route handler.
+ */
+const isFrameworkPropagationCall = (callExpression, names) =>
+    callExpression.callee?.type === 'Identifier' &&
+    callExpression.callee.name === 'next' &&
+    (callExpression.arguments || []).some((argument) => nodeReferencesName(argument, names));
+
+const isPreservingCall = (callExpression, names, side, ancestors = [], reporters = defaultErrorReporters) => {
     if (!nodeReferencesName(callExpression, names)) return false;
     if (hasOptionalCallBoundary(callExpression, ancestors)) return false;
-    if (isUnderConditionalControlFlow(ancestors)) return false;
     if (isConsoleMember(callExpression.callee)) return false;
     if (isPromiseRejectCall(callExpression)) return true;
+    if (isFrameworkPropagationCall(callExpression, names)) return true;
+    if (matchesConfiguredReporter(callExpression, reporters)) return true;
     if (side === 'client') return isClientErrorHandlerCall(callExpression);
     if (side === 'server') return isServerErrorReporterCall(callExpression);
 
     return isClientErrorHandlerCall(callExpression) || isServerErrorReporterCall(callExpression);
 };
 
-const handlerPreservesCaughtError = (node, names, side) => {
+/**
+ * Is the caught error handed back to the caller as a value?
+ *
+ * `return { ok: false, message: error.message }` and
+ * `results.push({ state: 'unavailable', message: describeError(error) })` both
+ * surface the failure in the API's own vocabulary. That is a designed
+ * degradation path, not a loss, so it counts as preservation.
+ */
+const handlerSurfacesCaughtError = (node, names) => {
+    let surfaces = false;
+
+    traverseNode(node, (child) => {
+        if (child.type === 'ReturnStatement' && nodeReferencesName(child.argument, names)) surfaces = true;
+
+        if (
+            child.type === 'CallExpression' &&
+            ['push', 'unshift', 'add', 'set'].includes(getCalleePropertyName(child.callee) || '') &&
+            (child.arguments || []).some((argument) => nodeReferencesName(argument, names))
+        ) {
+            surfaces = true;
+        }
+    });
+
+    return surfaces;
+};
+
+/**
+ * Is preservation guarded by a condition that tests the caught error itself?
+ *
+ * `if (!(error instanceof ExpectedPause)) report(error)` is deliberate
+ * filtering: the author chose which failures are worth reporting, which is a
+ * decision rather than a swallow. `if (app) app.reportError(error)` is not: it
+ * gates on whether the reporter exists, so the error is lost whenever it does
+ * not. Only the first is accepted.
+ */
+const isGuardedByErrorPredicate = (ancestors, names) =>
+    ancestors.some(({ node, childKey }) => {
+        if (node.type === 'IfStatement' && (childKey === 'consequent' || childKey === 'alternate'))
+            return nodeReferencesName(node.test, names);
+        if (node.type === 'ConditionalExpression' && (childKey === 'consequent' || childKey === 'alternate'))
+            return nodeReferencesName(node.test, names);
+        if (node.type === 'LogicalExpression' && childKey === 'right') return nodeReferencesName(node.left, names);
+        if (node.type === 'SwitchCase' && childKey === 'consequent') return true;
+
+        return false;
+    });
+
+const preservationSurvivesControlFlow = (ancestors, names) =>
+    !isUnderConditionalControlFlow(ancestors) || isGuardedByErrorPredicate(ancestors, names);
+
+const handlerPreservesCaughtError = (node, names, side, reporters = defaultErrorReporters) => {
     let preserves = false;
 
     traverseNode(node, (child, _parent, _parentKey, ancestors) => {
         if (
             child.type === 'ThrowStatement' &&
             nodeReferencesName(child.argument, names) &&
-            !isUnderConditionalControlFlow(ancestors)
+            preservationSurvivesControlFlow(ancestors, names)
+        ) {
+            preserves = true;
+        }
+        if (
+            child.type === 'CallExpression' &&
+            isPreservingCall(child, names, side, ancestors, reporters) &&
+            preservationSurvivesControlFlow(ancestors, names)
         ) {
             preserves = true;
         }
-        if (child.type === 'CallExpression' && isPreservingCall(child, names, side, ancestors)) preserves = true;
     });
 
+    if (!preserves && handlerSurfacesCaughtError(node, names)) preserves = true;
+
     return preserves;
 };
 
@@ -245,10 +344,22 @@ const createSwallowedErrorRule = () => ({
             unpreserved:
                 'Caught error `{{name}}` is used but not routed through the standard error path. Rethrow it, call app.reportError on the server, or call app.handleError on the client.',
         },
-        schema: [],
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    // `receiver.method` or a bare `method`. A project whose error
+                    // path is not `app.reportError` names it here rather than
+                    // being told its own convention is a swallow.
+                    reporters: { type: 'array', items: { type: 'string' } },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     create(context) {
         const side = getErrorHandlingSide(context.filename || context.getFilename?.() || '');
+        const reporters = context.options?.[0]?.reporters || defaultErrorReporters;
         const reportHandler = (node, params, body) => {
             const names = params.flatMap((param) => collectPatternNames(param));
             if (names.length === 0) {
@@ -262,7 +373,7 @@ const createSwallowedErrorRule = () => ({
                 return;
             }
 
-            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side)) {
+            if (!handlerPreservesCaughtError(body, collectDerivedErrorNames(body, names), side, reporters)) {
                 context.report({ node, messageId: 'unpreserved', data: { name: referencedName } });
             }
         };
@@ -287,6 +398,85 @@ const createSwallowedErrorRule = () => ({
     },
 });
 
+const boundaryTagPattern = /(^|\s)@boundary(\s|$)/;
+
+/**
+ * Is this `unknown` inside a function whose return type is a type predicate?
+ *
+ * Narrowing an untrusted value is the entire job of a guard, so `(value: unknown):
+ * value is DomainField` is the correct signature. Any narrower input type would
+ * defeat the guard it belongs to.
+ */
+const isWithinTypeGuardSignature = (ancestors) =>
+    ancestors.some(({ node }) => {
+        const returnType = node?.returnType?.typeAnnotation;
+        return returnType?.type === 'TSTypePredicate';
+    });
+
+const isWithinCatchParameter = (ancestors) =>
+    ancestors.some(({ node, childKey }) => node?.type === 'CatchClause' && childKey === 'param');
+
+const createNoLooseUnknownRule = () => ({
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `unknown` except where a value genuinely crosses a trust boundary.',
+        },
+        messages: {
+            looseUnknown:
+                '`unknown` hides a contract that should be typed. Define the explicit type, or, when the value really does arrive from outside (a parsed response, a provider payload, a caught error), document it with a `@boundary` comment saying where it comes from.',
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = getSourceCode(context);
+
+        // A `@boundary` tag anywhere above the declaration marks a deliberate
+        // trust boundary. Requiring the tag rather than allowing `unknown`
+        // silently keeps the boundaries greppable and forces a written reason.
+        const hasBoundaryTag = (node) => {
+            if (!sourceCode) return false;
+
+            const comments = sourceCode.getCommentsBefore?.(node) || [];
+            if (comments.some((comment) => boundaryTagPattern.test(comment.value))) return true;
+
+            let current = node.parent;
+            let depth = 0;
+            while (current && depth < 6) {
+                const ancestorComments = sourceCode.getCommentsBefore?.(current) || [];
+                if (ancestorComments.some((comment) => boundaryTagPattern.test(comment.value))) return true;
+                current = current.parent;
+                depth += 1;
+            }
+
+            return false;
+        };
+
+        return {
+            TSUnknownKeyword(node) {
+                const ancestors = [];
+                let current = node.parent;
+                while (current) {
+                    ancestors.push({ childKey: null, node: current });
+                    current = current.parent;
+                }
+
+                // TypeScript itself types a catch binding as `unknown`, so banning
+                // it there bans the language's own contract.
+                if (node.parent?.type === 'TSTypeAnnotation' && node.parent.parent?.type === 'Identifier') {
+                    const owner = node.parent.parent.parent;
+                    if (owner?.type === 'CatchClause') return;
+                }
+                if (isWithinCatchParameter(ancestors)) return;
+                if (isWithinTypeGuardSignature(ancestors)) return;
+                if (hasBoundaryTag(node)) return;
+
+                context.report({ node, messageId: 'looseUnknown' });
+            },
+        };
+    },
+});
+
 const createNoAppImportRule = () => ({
     meta: {
         type: 'problem',
@@ -545,6 +735,7 @@ const createRequireDocAnchorRule = () => ({
                 type: 'object',
                 properties: {
                     definitions: { type: 'array', items: { type: 'string' } },
+                    exclude: { type: 'array', items: { type: 'string' } },
                     include: { type: 'array', items: { type: 'string' } },
                     requiredTags: { type: 'array', items: { enum: docAnchorTags } },
                     serviceBasePattern: { type: 'string' },
@@ -558,15 +749,22 @@ const createRequireDocAnchorRule = () => ({
         const definitions = options.definitions || defaultDocAnchorDefinitions;
         const requiredTags = options.requiredTags || ['docs'];
         const includes = options.include || [];
+        const excludes = options.exclude || [];
         const serviceBasePattern = new RegExp(options.serviceBasePattern || 'Service$');
         const filename = context.filename || context.getFilename?.() || '';
 
+        // Infrastructure carries no feature contract, so a project lists those
+        // paths here rather than anchoring them to a pack that does not exist.
+        // An excluded file may still declare anchors, and `valid-doc-anchor`
+        // keeps checking them.
+        const excluded = matchesIncludeGlob(filename, excludes);
+
         let reported = false;
 
         const reportMissing = (node, subject) => {
             // One report per file: a service class and an include glob can both
             // match, and repeating the same instruction adds no information.
-            if (reported) return;
+            if (reported || excluded) return;
 
             const anchors = collectFileDocAnchors(context);
             if (anchors.entries.length === 0) {
@@ -661,7 +859,13 @@ const createValidDocAnchorRule = () => ({
     },
 });
 
-const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = [], ignores = [] } = {}) => [
+const createProteumEslintConfig = ({
+    docAnchors = 'warn',
+    errorReporters = defaultErrorReporters,
+    excludeDocAnchors = [],
+    includeDocAnchors = [],
+    ignores = [],
+} = {}) => [
     {
         ignores: [...defaultIgnores, ...ignores],
     },
@@ -687,6 +891,7 @@ const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = []
             proteum: {
                 rules: {
                     'no-app-import': createNoAppImportRule(),
+                    'no-loose-unknown': createNoLooseUnknownRule(),
                     'no-swallowed-caught-error': createSwallowedErrorRule(),
                     'require-doc-anchor': createRequireDocAnchorRule(),
                     'valid-doc-anchor': createValidDocAnchorRule(),
@@ -699,24 +904,27 @@ const createProteumEslintConfig = ({ docAnchors = 'warn', includeDocAnchors = []
         rules: {
             '@typescript-eslint/no-explicit-any': 'error',
             'proteum/no-app-import': 'error',
-            'proteum/no-swallowed-caught-error': 'error',
+            'proteum/no-swallowed-caught-error': ['error', { reporters: errorReporters }],
             // Missing anchors warn by default so adopting apps see the backlog
             // without a failing build; pass `docAnchors: 'error'` once backfilled.
             // Routes, controllers and service classes are covered automatically.
             // `includeDocAnchors` opts in extra paths, which is how a project
             // covers the feature-owning components without dragging in every
             // presentational primitive.
-            'proteum/require-doc-anchor': [docAnchors, { include: includeDocAnchors }],
+            'proteum/require-doc-anchor': [
+                docAnchors,
+                { exclude: excludeDocAnchors, include: includeDocAnchors },
+            ],
             // A stale anchor is always an error: it only fires on files that
             // already opted in, and a pointer to a deleted document is worse
             // than no pointer at all.
             'proteum/valid-doc-anchor': docAnchors === 'off' ? 'off' : 'error',
+            // Replaces the old bare `TSUnknownKeyword` selector. A selector has no
+            // context, so it could not tell an internal contract that should be
+            // typed from a value that genuinely arrives from outside.
+            'proteum/no-loose-unknown': 'error',
             'no-restricted-syntax': [
                 'error',
-                {
-                    selector: 'TSUnknownKeyword',
-                    message: 'Do not use `unknown`; define an explicit type instead.',
-                },
                 {
                     selector: createZodTypeFactorySelector('any'),
                     message: 'Do not use Zod `any()` schemas; define an explicit schema instead.',

package/package.json

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

package/tests/docs-check.test.cjs

@@ -160,6 +160,23 @@ test('docs check reports a feature pack that no code points at', () => {
     assert.deepEqual(orphans.map((finding) => finding.subject), ['docs/features/orphan']);
 });
 
+test('docs check lets a retired or non-code pack opt out of the orphan report', () => {
+    const root = createRoot();
+    writeFile(root, 'docs/features/search/README.md', '# Search\n');
+    writeFile(root, 'docs/features/pro-preview/README.md', '# Pro Preview\n\n> RETIRED 2026-07-07. Superseded.\n');
+    writeFile(root, 'docs/features/persona-journeys/README.md', '# Personas\n\ncode-owned: false\n');
+    writeFile(root, 'docs/features/still-orphaned/README.md', '# Orphan\n');
+    writeFile(
+        root,
+        'apps/product/server/controllers/search.ts',
+        '/**\n * @docs docs/features/search\n */\nexport default {};\n',
+    );
+
+    const orphans = kinds(buildDocsCheckReport(root), 'orphan-feature-pack');
+
+    assert.deepEqual(orphans.map((finding) => finding.subject), ['docs/features/still-orphaned']);
+});
+
 test('docs check ignores generated and vendored directories', () => {
     const root = createRoot();
     writeFile(root, 'docs/features/search/README.md', '# Search\n');

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

@@ -0,0 +1,228 @@
+const assert = require('node:assert/strict');
+const { Linter } = require('eslint');
+
+const { createProteumEslintConfig } = require('../eslint.js');
+
+const lint = (code, filename = 'server/example.ts', options) => {
+    const linter = new Linter({ configType: 'flat' });
+    return linter.verify(code, createProteumEslintConfig(options), { filename });
+};
+
+const looseUnknownRuleId = 'proteum/no-loose-unknown';
+const swallowedRuleId = 'proteum/no-swallowed-caught-error';
+const count = (messages, ruleId) => messages.filter((message) => message.ruleId === ruleId).length;
+
+/*----------------------------------
+- no-loose-unknown
+----------------------------------*/
+
+test('loose unknown is still reported on an ordinary contract', () => {
+    const messages = lint(`export type TRow = { value: unknown };`);
+
+    assert.equal(count(messages, looseUnknownRuleId), 1);
+});
+
+test('unknown is allowed on a catch binding, which is how TypeScript types it', () => {
+    const messages = lint(`
+        export const run = () => {
+            try {
+                risky();
+            } catch (error: unknown) {
+                throw error;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('unknown is allowed as the input of a type guard', () => {
+    const messages = lint(`
+        export const isDomainField = (value: unknown): value is string => typeof value === 'string';
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('unknown is allowed when the trust boundary is documented', () => {
+    const messages = lint(`
+        /** @boundary HumbleWorth prediction output, shape owned by the provider. */
+        export const parseOutput = (output: unknown) => output;
+    `);
+
+    assert.equal(count(messages, looseUnknownRuleId), 0);
+});
+
+test('an undocumented parse boundary is still reported', () => {
+    const messages = lint(`export const parseOutput = (output: unknown) => output;`);
+
+    assert.equal(count(messages, looseUnknownRuleId), 1);
+});
+
+/*----------------------------------
+- no-swallowed-caught-error
+----------------------------------*/
+
+test('express next(error) counts as propagation', () => {
+    const messages = lint(`
+        export const handler = async (req, res, next) => {
+            try {
+                await load();
+            } catch (error) {
+                next(error);
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a configured reporter counts as preservation', () => {
+    const source = `
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    this.app.reportError(error, { source: 'scan', code: 'failed' });
+                }
+            }
+        }
+    `;
+
+    assert.equal(count(lint(source), swallowedRuleId), 0);
+
+    // A project whose error path has another name declares it rather than being
+    // told its own convention is a swallow.
+    const custom = `
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    this.app.report('scan failed', error);
+                }
+            }
+        }
+    `;
+
+    assert.equal(count(lint(custom), swallowedRuleId), 1);
+    assert.equal(
+        count(lint(custom, 'server/example.ts', { errorReporters: ['app.reportError', 'app.report'] }), swallowedRuleId),
+        0,
+    );
+});
+
+test('conditional preservation counts, because deliberate filtering is not a swallow', () => {
+    const messages = lint(`
+        export class Scanner {
+            public async run() {
+                try {
+                    await this.scan();
+                } catch (error) {
+                    if (!(error instanceof ExpectedPause)) {
+                        this.app.reportError(error, { source: 'scan', code: 'failed' });
+                    }
+                }
+            }
+        }
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a guard on the reporter existing is still a swallow, unlike a guard on the error', () => {
+    // Filtering by what the error is: a decision.
+    const filtered = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                if (error.code !== 'EXPECTED') app.reportError(error);
+            }
+        };
+    `);
+    assert.equal(count(filtered, swallowedRuleId), 0);
+
+    // Gating on whether the reporter exists: the error vanishes when it does not.
+    const gated = lint(`
+        export const run = async (app) => {
+            try {
+                await load();
+            } catch (error) {
+                if (app) app.reportError(error);
+            }
+        };
+    `);
+    assert.equal(count(gated, swallowedRuleId), 1);
+});
+
+test('a guarded rethrow counts as preservation', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                if (error.code !== 'ENOENT') throw error;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('an error surfaced as a returned result counts as preservation', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                return { ok: false, message: error.message };
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('an error pushed into a result collection counts as preservation', () => {
+    const messages = lint(`
+        export const run = async (results) => {
+            try {
+                await load();
+            } catch (error) {
+                results.push({ state: 'unavailable', message: describeError(error) });
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 0);
+});
+
+test('a console-only catch is still reported', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                console.error('load failed', error);
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 1);
+});
+
+test('a discarded error is still reported', () => {
+    const messages = lint(`
+        export const run = async () => {
+            try {
+                await load();
+            } catch (error) {
+                return null;
+            }
+        };
+    `);
+
+    assert.equal(count(messages, swallowedRuleId), 1);
+});

package/tests/eslint-rules.test.cjs

@@ -541,6 +541,50 @@ test('proteum lint accepts an included file once it carries an anchor', () => {
     assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
 });
 
+test('proteum lint exempts infrastructure paths listed in excludeDocAnchors', () => {
+    const { root } = createDocProject();
+    const options = { docAnchors: 'warn', excludeDocAnchors: ['server/services/Utils/**', 'server/routes/debug.ts'] };
+
+    const utilService = lint(
+        `export default class FetchService extends Service {}`,
+        path.join(root, 'server', 'services', 'Utils', 'Fetch', 'index.ts'),
+        options,
+    );
+    assert.equal(messagesFor(utilService, requireDocAnchorRuleId).length, 0);
+
+    const debugRoute = lint(
+        `export default defineServerRoutes(() => null);`,
+        path.join(root, 'server', 'routes', 'debug.ts'),
+        options,
+    );
+    assert.equal(messagesFor(debugRoute, requireDocAnchorRuleId).length, 0);
+
+    // A service outside the excluded paths is still required to anchor.
+    const covered = lint(
+        `export default class SearchService extends Service {}`,
+        path.join(root, 'server', 'services', 'Domains', 'search', 'index.ts'),
+        options,
+    );
+    assert.equal(messagesFor(covered, requireDocAnchorRuleId).length, 1);
+});
+
+test('proteum lint still validates anchors declared on an excluded file', () => {
+    const { root } = createDocProject();
+    const messages = lint(
+        `
+            /**
+             * @docs docs/features/deleted-feature
+             */
+            export default class FetchService extends Service {}
+        `,
+        path.join(root, 'server', 'services', 'Utils', 'Fetch', 'index.ts'),
+        { docAnchors: 'warn', excludeDocAnchors: ['server/services/Utils/**'] },
+    );
+
+    assert.equal(messagesFor(messages, requireDocAnchorRuleId).length, 0);
+    assert.equal(messagesFor(messages, validDocAnchorRuleId).length, 1);
+});
+
 test('proteum lint does not require a doc anchor on error routes', () => {
     const { root } = createDocProject();
     const messages = lint(