@adonis-agora/filter 0.7.0 → 0.8.0

package/dist/src/filterable_mixin.js

@@ -0,0 +1,46 @@
+import { HttpContext } from '@adonisjs/core/http';
+import { applyFilterFromRequest, } from './apply_from_request.js';
+import { stashPagination } from './pagination_stash.js';
+export function Filterable(superclass) {
+    class FilterableModel extends superclass {
+        /** The filter this model is read through. A thunk, so the filter may import the model back. */
+        static $filter;
+        /**
+         * Apply the model's filter to a fresh query and hand back the **query builder** plus the
+         * pagination the request resolved to — filters, search and sort applied, nothing executed.
+         * Compose whatever else the endpoint needs on the builder, then page it with
+         * `filterPaginate()` (no arguments) or `paginate(page, size)`.
+         */
+        static async filter(ctx, filter, options) {
+            // `this` is the model the static was called on (a subclass of the mixin), which is exactly
+            // what these helpers need — the rule's suggestion (name the class) would pin every model to
+            // the anonymous mixin class instead.
+            // biome-ignore lint/complexity/noThisInStatic: `this` is the calling model, by design.
+            const model = this;
+            const target = filter ?? model.$filter?.();
+            if (!target) {
+                throw new Error(
+                // biome-ignore lint/complexity/noThisInStatic: names the model the call was made on.
+                `${this.name} has no filter — declare \`static $filter = () => YourFilter\` on the model, or pass one to filter().`);
+            }
+            // biome-ignore lint/complexity/noThisInStatic: the calling model builds its own query.
+            const query = this.query();
+            const pagination = await applyFilterFromRequest(query, target, ctx ?? HttpContext.getOrFail(), options);
+            stashPagination(query, pagination);
+            return { query, page: pagination.page, size: pagination.size };
+        }
+        /**
+         * The same, then `paginate(page, size)` with the pagination the request resolved to — the
+         * whole list endpoint in one call.
+         */
+        static async filterPaginate(ctx, filter, options) {
+            // biome-ignore lint/complexity/noThisInStatic: `this` is the calling model, by design.
+            const model = this;
+            // biome-ignore lint/complexity/noThisInStatic: forwards the call to the same model.
+            const { query, page, size } = await model.filter.call(this, ctx, filter, options);
+            return query.paginate(page, size);
+        }
+    }
+    return FilterableModel;
+}
+//# sourceMappingURL=filterable_mixin.js.map

package/dist/src/filterable_mixin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filterable_mixin.js","sourceRoot":"","sources":["../../src/filterable_mixin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOlD,OAAO,EAGL,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAwDxD,MAAM,UAAU,UAAU,CACxB,UAAa;IAEb,MAAM,eAAgB,SAAQ,UAAU;QACtC,+FAA+F;QAC/F,MAAM,CAAC,OAAO,CAAkC;QAEhD;;;;;WAKG;QACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAEjB,GAA0B,EAC1B,MAAiC,EACjC,OAAiC;YAEjC,2FAA2F;YAC3F,4FAA4F;YAC5F,qCAAqC;YACrC,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAyC,CAAC;YACxD,MAAM,MAAM,GAAG,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK;gBACb,qFAAqF;gBACrF,GAAG,IAAI,CAAC,IAAI,uGAAuG,CACpH,CAAC;YACJ,CAAC;YAED,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAkC,CAAC;YAC3D,MAAM,UAAU,GAAG,MAAM,sBAAsB,CAC7C,KAAc,EACd,MAAe,EACf,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,EAC9B,OAAO,CACR,CAAC;YACF,eAAe,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACnC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,CAAC;QACjE,CAAC;QAED;;;WAGG;QACH,MAAM,CAAC,KAAK,CAAC,cAAc,CAEzB,GAA0B,EAC1B,MAAiC,EACjC,OAAiC;YAEjC,uFAAuF;YACvF,MAAM,KAAK,GAAG,IAAyC,CAAC;YACxD,oFAAoF;YACpF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YAClF,OAAQ,KAAsC,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAEjE,CAAC;QACJ,CAAC;KACF;IAED,OAAO,eAAwD,CAAC;AAClE,CAAC"}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.8.0";
 export type { ColumnFilter, FilterOperator, FilterOperatorAlias, FilterOperatorInput, } from './operators.js';
 export { FILTER_OPERATORS, OPERATOR_ALIASES } from './operators.js';
 export { InvalidColumnFilterError, MAX_FILTER_DEPTH, normalizeOperator, validateColumnFilter, validateColumnFilters, } from './validate-column-filter.js';
@@ -16,6 +16,13 @@ export type { FilterClientEntry, FilterClientManifest, FilterFieldKind, FilterFi
 export type { DefineFilterOptions, FilterSpec, RelationColumns, RelationSpec, TenantResolver, TenantScopeSpec, } from './filter_spec.js';
 export { applyCursorFromRequest, applyFilterFromRequest } from './apply_from_request.js';
 export type { ApplyCursorFromRequestOptions, ApplyFromRequestOptions, FilterRequestContext, } from './apply_from_request.js';
+export { BaseModelFilter } from './base_model_filter.js';
+export { filterFor, filterable, searchable, sortable } from './decorators.js';
+export type { DualDecorator, StandardDecoratorContext } from './decorators.js';
+export { dispatchKeys, isFilterClass, methodForKey, specFromFilterClass, } from './filter_class.js';
+export type { FilterClass } from './filter_class.js';
+export { Filterable } from './filterable_mixin.js';
+export type { FilterableModelStatics } from './filterable_mixin.js';
 export { registerFilterMacros } from './lucid_macros.js';
 export type { MacroableQueryBuilder } from './lucid_macros.js';
 export { parseDistinct, parseFilterRequest, parseSort, toColumnFilters } from './parse_request.js';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/dist/src/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.6.0';
+export const VERSION = '0.8.0';
 export { FILTER_OPERATORS, OPERATOR_ALIASES } from './operators.js';
 export { InvalidColumnFilterError, MAX_FILTER_DEPTH, normalizeOperator, validateColumnFilter, validateColumnFilters, } from './validate-column-filter.js';
 export { isOperatorObject, valueToColumnFilters } from './value-shape.js';
@@ -9,6 +9,10 @@ export { discoverAggregateSources } from './aggregate.js';
 export { defineFilter, FilterDefinitionError, specToFilterConfig, } from './filter_spec.js';
 export { filterableFieldPaths, generateFilterClient, generateFilterClients, sortableFieldPaths, } from './generate_client.js';
 export { applyCursorFromRequest, applyFilterFromRequest } from './apply_from_request.js';
+export { BaseModelFilter } from './base_model_filter.js';
+export { filterFor, filterable, searchable, sortable } from './decorators.js';
+export { dispatchKeys, isFilterClass, methodForKey, specFromFilterClass, } from './filter_class.js';
+export { Filterable } from './filterable_mixin.js';
 export { registerFilterMacros } from './lucid_macros.js';
 export { parseDistinct, parseFilterRequest, parseSort, toColumnFilters } from './parse_request.js';
 export { parseSpatieRequest } from './spatie_parser.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAQ/B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAe1D,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAMzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,yBAAyB,GAK1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAQ/B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAe1D,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAMzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE9E,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,yBAAyB,GAK1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/lucid_macros.d.ts

@@ -1,5 +1,7 @@
 import { type ApplyFromRequestOptions, type FilterRequestContext } from './apply_from_request.js';
+import { type FilterClass } from './filter_class.js';
 import type { FilterSpec } from './filter_spec.js';
+import type { ResolvedPagination } from './runner.js';
 /**
  * The static slice of a Lucid query-builder class we register onto: Adonis'
  * `Macroable.macro(name, fn)` adds `fn` to the builder prototype so every query
@@ -45,12 +47,41 @@ declare module '@adonisjs/lucid/types/model' {
          * request scope (e.g. a job/command), where there is no ambient context.
          */
         applyFilterFromRequest(spec: FilterSpec, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): this;
+        /**
+         * The same for a filter **class**: resolved through the IoC container (so `@inject()` works),
+         * `setup()` first, then every request key the class owns a method for.
+         *
+         * Resolution is async, so this returns a promise — of the resolved `{ page, size }`, not of
+         * the builder (a Lucid builder is thenable, so awaiting a promise of one would run the query).
+         * The builder is the one you called it on, still yours to compose on:
+         *
+         * ```ts
+         * const query = User.query().whereNull('deletedAt')
+         * const { page, size } = await query.applyFilterFromRequest(UserFilter)
+         * return query.preload('team').paginate(page, size)
+         * ```
+         */
+        applyFilterFromRequest(filter: FilterClass, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): Promise<ResolvedPagination>;
         /**
          * Apply a {@link FilterSpec} from the request context and paginate with the
          * resolved `{ page, size }`, returning Lucid's paginator — filter + paginate
          * in one terminal call. `ctx` is optional (see {@link applyFilterFromRequest}).
          */
         filterPaginate(spec: FilterSpec, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): ReturnType<this['paginate']>;
+        /** The filter-class form of {@link filterPaginate} — async, for the same reason. */
+        filterPaginate(filter: FilterClass, ctx?: FilterRequestContext, options?: ApplyFromRequestOptions): Promise<Awaited<ReturnType<this['paginate']>>>;
+        /**
+         * Page a query that has **already** been filtered (by the model's `filter()` or by the
+         * `applyFilterFromRequest` macro) with the `{ page, size }` that call resolved — so a
+         * controller can keep composing on the builder and still page it the way the request asked.
+         *
+         * ```ts
+         * const query = await User.filter(ctx)
+         * query.whereNotNull('confirmedAt')
+         * return query.filterPaginate()
+         * ```
+         */
+        filterPaginate(): ReturnType<this['paginate']>;
     }
 }
 //# sourceMappingURL=lucid_macros.d.ts.map

package/dist/src/lucid_macros.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lucid_macros.d.ts","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAanD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,IAAI,CAoBnF;AAED,OAAO,QAAQ,6BAA6B,CAAC;IAC3C,UAAU,yBAAyB,CAAC,KAAK,SAAS,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC;QACxF;;;;;;;;;WASG;QACH,sBAAsB,CACpB,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,IAAI,CAAC;QACR;;;;WAIG;QACH,cAAc,CACZ,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;KACjC;CACF"}
+{"version":3,"file":"lucid_macros.d.ts","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,KAAK,WAAW,EAAiB,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAYtD;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,GAAG,IAAI,CAAC;CAC7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,iBAAiB,EAAE,qBAAqB,GAAG,IAAI,CA+CnF;AAED,OAAO,QAAQ,6BAA6B,CAAC;IAC3C,UAAU,yBAAyB,CAAC,KAAK,SAAS,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC;QACxF;;;;;;;;;WASG;QACH,sBAAsB,CACpB,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,IAAI,CAAC;QACR;;;;;;;;;;;;;WAaG;QACH,sBAAsB,CACpB,MAAM,EAAE,WAAW,EACnB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAC/B;;;;WAIG;QACH,cAAc,CACZ,IAAI,EAAE,UAAU,EAChB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAChC,oFAAoF;QACpF,cAAc,CACZ,MAAM,EAAE,WAAW,EACnB,GAAG,CAAC,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;QAClD;;;;;;;;;;WAUG;QACH,cAAc,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;KAChD;CACF"}

package/dist/src/lucid_macros.js

@@ -1,5 +1,7 @@
 import { HttpContext } from '@adonisjs/core/http';
 import { applyFilterFromRequest, } from './apply_from_request.js';
+import { isFilterClass } from './filter_class.js';
+import { readPagination, stashPagination } from './pagination_stash.js';
 /**
  * O ctx da request para o macro: explícito, ou o `HttpContext` ativo lido do AsyncLocalStorage do
  * Adonis quando omitido. `getOrFail()` lança quando não há request em escopo (ex.: chamada dentro de
@@ -30,12 +32,34 @@ function resolveCtx(ctx) {
  * the same implementations.
  */
 export function registerFilterMacros(ModelQueryBuilder) {
-    ModelQueryBuilder.macro('applyFilterFromRequest', function (spec, ctx, options) {
-        applyFilterFromRequest(this, spec, resolveCtx(ctx), options);
+    ModelQueryBuilder.macro('applyFilterFromRequest', function (filter, ctx, options) {
+        // A class is resolved through the container, so this leg is async — and it resolves to the
+        // pagination rather than to the builder: a Lucid query builder is thenable, so a promise that
+        // resolved to one would execute the query instead of handing it back. You already hold the
+        // builder; `await query.applyFilterFromRequest(UserFilter)` gives you its `{ page, size }`.
+        if (isFilterClass(filter)) {
+            return applyFilterFromRequest(this, filter, resolveCtx(ctx), options).then((pagination) => {
+                stashPagination(this, pagination);
+                return pagination;
+            });
+        }
+        stashPagination(this, applyFilterFromRequest(this, filter, resolveCtx(ctx), options));
         return this;
     });
-    ModelQueryBuilder.macro('filterPaginate', function (spec, ctx, options) {
-        const { page, size } = applyFilterFromRequest(this, spec, resolveCtx(ctx), options);
+    ModelQueryBuilder.macro('filterPaginate', function (filter, ctx, options) {
+        // No filter argument: this query has already been through one (the model's `filter()`, or the
+        // `applyFilterFromRequest` macro), so page it with the pagination that call resolved.
+        if (filter === undefined) {
+            const stashed = readPagination(this);
+            if (!stashed) {
+                throw new Error('filterPaginate() was called with no filter on a query that has not been filtered. Pass the filter — filterPaginate(UserFilter) — or apply one first.');
+            }
+            return this.paginate(stashed.page, stashed.size);
+        }
+        if (isFilterClass(filter)) {
+            return applyFilterFromRequest(this, filter, resolveCtx(ctx), options).then(({ page, size }) => this.paginate(page, size));
+        }
+        const { page, size } = applyFilterFromRequest(this, filter, resolveCtx(ctx), options);
         return this.paginate(page, size);
     });
 }

package/dist/src/lucid_macros.js.map

@@ -1 +1 @@
-{"version":3,"file":"lucid_macros.js","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAGL,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAIjC;;;;;GAKG;AACH,SAAS,UAAU,CAAC,GAAqC;IACvD,OAAO,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;AACxC,CAAC;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,iBAAwC;IAC3E,iBAAiB,CAAC,KAAK,CAAC,wBAAwB,EAAE,UAEhD,IAAgB,EAChB,GAA0B,EAC1B,OAAiC;QAEjC,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAiD,CAAC,CAAC;IAEnD,iBAAiB,CAAC,KAAK,CAAC,gBAAgB,EAAE,UAExC,IAAgB,EAChB,GAA0B,EAC1B,OAAiC;QAEjC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QACpF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAiD,CAAC,CAAC;AACrD,CAAC"}
+{"version":3,"file":"lucid_macros.js","sourceRoot":"","sources":["../../src/lucid_macros.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAGL,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAoB,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGpE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxE;;;;;GAKG;AACH,SAAS,UAAU,CAAC,GAAqC;IACvD,OAAO,GAAG,IAAI,WAAW,CAAC,SAAS,EAAE,CAAC;AACxC,CAAC;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAAC,iBAAwC;IAC3E,iBAAiB,CAAC,KAAK,CAAC,wBAAwB,EAAE,UAEhD,MAAgC,EAChC,GAA0B,EAC1B,OAAiC;QAEjC,2FAA2F;QAC3F,8FAA8F;QAC9F,2FAA2F;QAC3F,4FAA4F;QAC5F,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;gBACxF,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;gBAClC,OAAO,UAAU,CAAC;YACpB,CAAC,CAAC,CAAC;QACL,CAAC;QACD,eAAe,CAAC,IAAI,EAAE,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAiD,CAAC,CAAC;IAEnD,iBAAiB,CAAC,KAAK,CAAC,gBAAgB,EAAE,UAExC,MAAiC,EACjC,GAA0B,EAC1B,OAAiC;QAEjC,8FAA8F;QAC9F,sFAAsF;QACtF,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACb,sJAAsJ,CACvJ,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,OAAO,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,IAAI,CACxE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAsB,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAClE,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;QACtF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAiD,CAAC,CAAC;AACrD,CAAC"}

package/dist/src/pagination_stash.d.ts

@@ -0,0 +1,4 @@
+import type { ResolvedPagination } from './runner.js';
+export declare function stashPagination(query: unknown, pagination: ResolvedPagination): void;
+export declare function readPagination(query: unknown): ResolvedPagination | undefined;
+//# sourceMappingURL=pagination_stash.d.ts.map

package/dist/src/pagination_stash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination_stash.d.ts","sourceRoot":"","sources":["../../src/pagination_stash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAWtD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAIpF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAG7E"}

package/dist/src/pagination_stash.js

@@ -0,0 +1,19 @@
+/**
+ * Where a filtered query remembers the pagination the request resolved to.
+ *
+ * The builder is handed back to the caller so the endpoint can keep composing on it; the page and
+ * size it already resolved ride along on this symbol, so a later `filterPaginate()` needs no
+ * arguments and no second read of the request.
+ */
+const PAGINATION = Symbol.for('@adonis-agora/filter:pagination');
+export function stashPagination(query, pagination) {
+    if (query !== null && typeof query === 'object') {
+        query[PAGINATION] = pagination;
+    }
+}
+export function readPagination(query) {
+    if (query === null || typeof query !== 'object')
+        return undefined;
+    return query[PAGINATION];
+}
+//# sourceMappingURL=pagination_stash.js.map

package/dist/src/pagination_stash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination_stash.js","sourceRoot":"","sources":["../../src/pagination_stash.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;AAEjE,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,UAA8B;IAC5E,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,KAAiC,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;IAC9D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClE,OAAQ,KAAwD,CAAC,UAAU,CAAC,CAAC;AAC/E,CAAC"}

package/dist/stubs/main.d.ts

@@ -0,0 +1,3 @@
+/** Absolute path to this package's stubs, handed to `codemods.makeUsingStub`. */
+export declare const stubsRoot: string;
+//# sourceMappingURL=main.d.ts.map

package/dist/stubs/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,eAAO,MAAM,SAAS,QAAgD,CAAC"}

package/dist/stubs/main.js

@@ -0,0 +1,4 @@
+import { fileURLToPath } from 'node:url';
+/** Absolute path to this package's stubs, handed to `codemods.makeUsingStub`. */
+export const stubsRoot = fileURLToPath(new URL('./', import.meta.url));
+//# sourceMappingURL=main.js.map

package/dist/stubs/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../stubs/main.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/stubs/make/filter/main.stub

@@ -0,0 +1,45 @@
+{{#var filterName = string(entity.name).pascalCase().removeSuffix('Filter').toString() + 'Filter'}}
+{{#var modelName = string(entity.name).pascalCase().removeSuffix('Filter').toString()}}
+{{#var filterFileName = string(entity.name).snakeCase().removeSuffix('filter').toString() + '_filter'}}
+{{#var modelFileName = string(entity.name).snakeCase().removeSuffix('filter').toString()}}
+{{{
+  exports({
+    to: app.makePath('app/filters', entity.path, filterFileName + '.ts')
+  })
+}}}
+import { BaseModelFilter } from '@adonis-agora/filter'
+import type { ModelQueryBuilderContract } from '@adonisjs/lucid/types/model'
+import {{ modelName }} from '#models/{{ modelFileName }}'
+
+export default class {{ filterName }} extends BaseModelFilter {
+  declare $query: ModelQueryBuilderContract<typeof {{ modelName }}>
+
+  static model = {{ modelName }}
+
+  /** Columns clients may filter on with the standard operators — these need no method. */
+  static filterable = ['name']
+  /** Columns clients may sort on. Defaults to `filterable`. */
+  static sortable = ['createdAt']
+  /** Columns the free-text `search` term scans. */
+  static searchable = ['name']
+
+  static defaultSort = [{ field: 'createdAt', direction: 'desc' as const }]
+  static defaultSize = 25
+  static maxSize = 100
+
+  /**
+   * Runs on every call, before anything the request asked for — the place for a scope the client
+   * cannot relax (a tenant, a soft-delete guard, an ownership check).
+   */
+  setup() {
+    // this.$query.whereNull('deletedAt')
+  }
+
+  /**
+   * One method per request key that needs SQL of its own. `?filter[fullName]=silva` lands here;
+   * writing the method IS what exposes the key, so it needs no allow-list entry.
+   */
+  // fullName(value: string) {
+  //   this.$query.whereILike('full_name', `%${value}%`)
+  // }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/filter",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Server-side query filtering/sorting/pagination for AdonisJS — Spatie-style input, a Lucid adapter, and field allow-listing. Part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,10 @@
   },
   "files": [
     "dist/",
+    "stubs/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "sideEffects": false,
   "peerDependencies": {
@@ -59,6 +61,7 @@
   },
   "devDependencies": {
     "@adonisjs/assembler": "8.4.0",
+    "@tanstack/intent": "^0.3.2",
     "@adonisjs/core": "7.4.0",
     "@adonisjs/lucid": "22.4.2",
     "@types/luxon": "3.7.4",
@@ -80,12 +83,14 @@
     "query",
     "spatie",
     "pagination",
-    "agora"
+    "agora",
+    "tanstack-intent"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && pnpm run copy:stubs",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.typetest.json"
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.typetest.json",
+    "copy:stubs": "mkdir -p dist/stubs/make/filter && cp stubs/make/filter/main.stub dist/stubs/make/filter/main.stub"
   }
 }

package/skills/filter-basics/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: filter-basics
+description: >
+  Add Spatie/JSON:API-style query filtering to an AdonisJS endpoint with
+  @adonis-agora/filter. Covers parseFilterRequest(qs), applyFilter(query, input,
+  { allowed, sortable, searchable }) with the returned/clamped { page, size },
+  the declarative defineFilter + applyFilterFromRequest flow (tenant scope,
+  defaultFilters, defaultSort, defaultSize/maxSize), the optional provider
+  macros .applyFilterFromRequest() / .filterPaginate(), wire format parsing
+  (filter[field][op]=value, sort=-createdAt, page/size), and input sourcing from
+  query string, POST body, or a nested key. Use when building a filtered list
+  endpoint, wiring a reusable filter policy, or deciding free functions vs macros.
+metadata:
+  type: core
+  library: "@adonis-agora/filter"
+  library_version: "0.7.0"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-filter:docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/controllers.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/filter-classes.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/provider.mdx"
+  - "DavideCarvalho/adonis-filter:docs/guides/operators.mdx"
+---
+
+# Filter basics: parse a request, apply it to a Lucid query
+
+The whole server surface is two functions: `parseFilterRequest(request.qs())`
+reshapes the request into a structured `FilterInput`, then
+`applyFilter(query, input, config)` validates it, prunes it against an
+allow-list, mutates your Lucid query in place, and returns the resolved
+`{ page, size }`. No config file, no decorators; the optional service provider
+only adds chainable macros.
+
+## Setup
+
+```bash
+npm install @adonis-agora/filter
+```
+
+```typescript
+// app/controllers/users_controller.ts
+import type { HttpContext } from '@adonisjs/core/http'
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+import User from '#models/user'
+
+export default class UsersController {
+  async index({ request }: HttpContext) {
+    const input = parseFilterRequest(request.qs())
+    const query = User.query()
+
+    const { page, size } = applyFilter(query, input, {
+      allowed: ['name', 'email', 'age', 'status'],
+      sortable: ['name', 'createdAt'],
+      searchable: ['name', 'email'],
+      defaultSize: 25,
+      maxSize: 100,
+    })
+
+    return query.paginate(page, size)
+  }
+}
+```
+
+```typescript
+// start/routes.ts
+import router from '@adonisjs/core/services/router'
+const UsersController = () => import('#controllers/users_controller')
+
+router.get('/users', [UsersController, 'index'])
+```
+
+A request like
+`GET /users?filter[status]=active&filter[age][gte]=18&search=fleet&sort=-createdAt&page=1&size=25`
+parses, validates, prunes against the allow-list, applies WHERE/ORDER BY/ILIKE,
+and returns `{ page: 1, size: 25 }` for `query.paginate()`.
+
+## Core patterns
+
+### 1. Two-function primitive — parse once, apply once
+
+`parseFilterRequest` is a pure reshape (no validation, no allow-listing);
+`applyFilter` owns validation and pruning. It reads any decoded object, so the
+same controller serves GET query strings and structured POST bodies:
+
+```typescript
+import { parseFilterRequest, applyFilter } from '@adonis-agora/filter'
+
+// GET — decoded query string
+const input = parseFilterRequest(request.qs())
+
+// POST /search — the body may be the flat Spatie shape or the structured
+// object the client builder's .build() returns ({ filter: { where }, sort, paginate })
+const bodyInput = parseFilterRequest(request.body())
+```
+
+Source: `docs/guides/controllers.mdx`, `docs/guides/operators.mdx`
+
+### 2. Reusable policies with defineFilter + applyFilterFromRequest
+
+When a policy spans endpoints, declare a `FilterSpec` once at module scope and
+apply it in one call. Server scope (tenant + `defaultFilters`) is injected
+before allow-listed request filters; `defaultSort` applies when the request has
+none:
+
+```typescript
+// app/filters/user_filter.ts
+import { defineFilter } from '@adonis-agora/filter'
+import User from '#models/user'
+
+export const userFilter = defineFilter({
+  filterable: ['name', 'email', 'age', 'status'],
+  sortable: ['name', 'createdAt'],
+  searchable: ['name', 'email'],
+  relations: { posts: { filterable: ['title', 'status'] } },
+  tenant: { column: 'tenantId', resolve: (ctx) => (ctx as any).auth.user!.tenantId },
+  defaultFilters: [{ field: 'deletedAt', operator: 'isNull' }],
+  defaultSort: [{ field: 'createdAt', direction: 'desc' }],
+  defaultSize: 25,
+  maxSize: 100,
+})
+```
+
+```typescript
+// app/controllers/users_controller.ts
+import { applyFilterFromRequest } from '@adonis-agora/filter'
+import { userFilter } from '#filters/user_filter'
+import User from '#models/user'
+
+async index(ctx: HttpContext) {
+  const query = User.query()
+  const { page, size } = applyFilterFromRequest(query, userFilter, ctx)
+  return query.paginate(page, size)
+}
+```
+
+Source: `docs/definitions/index.mdx`
+
+### 3. Optional macros — inline chaining
+
+Register the provider (`node ace add @adonis-agora/filter`, or add
+`() => import('@adonis-agora/filter/filter_provider')` under `providers` in
+`adonisrc.ts`) and every model query gains `.applyFilterFromRequest(spec)` /
+`.filterPaginate(spec)`:
+
+```typescript
+import { userFilter } from '#filters/user_filter'
+import User from '#models/user'
+
+// ctx read from AsyncLocalStorage inside a request
+return User.query().where('active', true).applyFilterFromRequest(userFilter)
+
+// filter + paginate in one terminal call
+return User.query().filterPaginate(userFilter)
+```
+
+The free `applyFilterFromRequest(query, spec, ctx, options?)` always needs an
+explicit `ctx` — the AsyncLocalStorage fallback exists only in the macro layer.
+
+Source: `docs/guides/provider.mdx`
+
+### 4. Pagination is returned, not applied
+
+`applyFilter` resolves `size = clamp(input.size ?? defaultSize ?? 25, 1, maxSize ?? 100)`
+and `page = max(1, input.page ?? 1)` but leaves execution to you — so you can
+paginate, run plain `.exec()`, or layer a DISTINCT projection on the same
+filtered query.
+
+Source: `docs/getting-started.mdx`, `docs/guides/filter-classes.mdx`
+
+## Common mistakes
+
+### [CRITICAL] Feeding raw request page/size to paginate()
+
+Wrong:
+
+```typescript
+const input = parseFilterRequest(request.qs())
+await User.query().paginate(input.page ?? 1, input.size ?? 25)
+```
+
+Correct:
+
+```typescript
+const query = User.query()
+const { page, size } = applyFilter(query, input, { allowed: ['name'], maxSize: 100 })
+return query.paginate(page, size)
+```
+
+`applyFilter` clamps size into `[1, maxSize]` and floors page at 1; values taken
+straight off the query string skip the clamp entirely, so `?size=500000`
+executes against the database.
+
+Source: docs/getting-started.mdx ("Why pagination is returned, not applied"); docs/guides/filter-classes.mdx (Pagination bounds)
+
+### [HIGH] Putting the tenant column in the allow-list
+
+Wrong:
+
+```typescript
+export const userFilter = defineFilter({
+  filterable: ['name', 'tenantId'], // client can now constrain tenantId too
+  tenant: { column: 'tenantId', resolve: (ctx) => ctx.tenantId },
+})
+```
+
+Correct:
+
+```typescript
+export const userFilter = defineFilter({
+  filterable: ['name'],
+  tenant: { column: 'tenantId', resolve: (ctx) => ctx.tenantId },
+})
+```
+
+The tenant scope always lands as trusted server policy; if the same column is
+also client-filterable, a sent value AND-combines with it and silently returns
+an empty result set. Same rule for pre-scoped queries: constrain before
+`applyFilter` and leave the column out of `allowed`.
+
+Source: docs/definitions/index.mdx ("Tenant scope is un-tamperable"); docs/guides/controllers.mdx
+
+### [MEDIUM] Expecting `search` to work without `searchable`
+
+Wrong:
+
+```typescript
+applyFilter(query, input, { allowed: ['name'] })
+// ?search=fleet is silently skipped — no searchable columns declared
+```
+
+Correct:
+
+```typescript
+applyFilter(query, input, {
+  allowed: ['name'],
+  searchable: ['name', 'email'],
+})
+```
+
+The free-text term only routes anywhere when `searchable` is non-empty;
+otherwise it is dropped with no error and rows come back unfiltered by search.
+
+Source: docs/guides/filter-classes.mdx ("searchable enables free-text search")
+
+See also: `../filter-safety/SKILL.md` (tightening the boundary before exposing
+the endpoint publicly), `../filter-definitions/SKILL.md` (growing the policy
+into a reusable spec).