@adula/kit 0.2.0-alpha.2 → 0.2.0-alpha.4

package/README.md

@@ -1,6 +1,6 @@
 # @adula/kit
 
-Experimental 0.2.0-alpha.2 resource framework for AdonisJS 7 and PostgreSQL 17. Node 24 or later is required. MIT licensed. The target is the complete approved 1.0 scope; it has not passed acceptance.
+Experimental 0.2.0-alpha.4 resource framework for AdonisJS 7 and PostgreSQL 17. Node 24 or later is required. MIT licensed. The target is the complete approved 1.0 scope; it has not passed acceptance.
 
 ## Install into a consumer
 
@@ -28,4 +28,4 @@ Doctor measures the deployment's `storage/uploads` directory and warns above 5 d
 
 ## Current limitations
 
-Attachment ownership, upload/download, storage migration, authentication lifecycle/rate limiting, generic resource UI and core administration have local integration consumers and tests. Real OAuth/SMTP, full Tuyau field contracts, human/performance acceptance, XState workflows, later business features, staging/offsite restoration and a genuine minor-version consumer upgrade remain open. Submission envelopes are durable records in pending_definition state, not running workflows. See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md). Version 0.2.0-alpha.2 targets alpha; the owner-authorized latest alias remains on 0.2.0-alpha.1.
+Attachment ownership, upload/download, storage migration, authentication lifecycle/rate limiting, generic resource UI and core administration have local integration consumers and tests. Real OAuth/SMTP, full Tuyau field contracts, human/performance acceptance, XState workflows, later business features, staging/offsite restoration and a genuine minor-version consumer upgrade remain open. Submission envelopes are durable records in pending_definition state, not running workflows. See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md). Version 0.2.0-alpha.4 targets alpha; the owner-authorized latest alias remains on 0.2.0-alpha.1.

package/build/agent/capabilities.md

@@ -1,13 +1,13 @@
 # Current capabilities
 
-Version 0.2.0-alpha.2, experimental alpha. Resource definitions and registry; six flat condition operators (typed limits documented in KIT_GAPS.md); CASL evaluation with structural ltree scope; JSON/Inertia resource CRUD; field contracts; keyset pagination; sequences/lookups/settings; soft deletion; optimistic concurrency; atomic inline writes/activity/outbox; deduplicated database listeners; org moves; attachment ownership/storage migration; saved views; core administration services; resource/module commands; copied shadcn UI and installation diagnostics.
+Version 0.2.0-alpha.4, experimental alpha. Resource definitions and registry; six flat condition operators (typed limits documented in KIT_GAPS.md); CASL evaluation with structural ltree scope; JSON/Inertia resource CRUD; field contracts; keyset pagination; sequences/lookups/settings; soft deletion; optimistic concurrency; atomic inline writes/activity/outbox; deduplicated database listeners; org moves; attachment ownership/storage migration; saved views (queries limited to fields the author may query); attachment fields with per-field `accept`/`maxSize` limits and daily pruning of unbound uploads; case-insensitive e-mail identity with ownership proof before OAuth linking; `adula:gaps report`; core administration services; resource/module commands; copied shadcn UI and installation diagnostics.
 
 The reference consumer wires authentication/session lifecycle, admin screens, authorized attachments, optional MCP, Redis actor caching, a queue worker, one scheduler and backup/restore drills. Educational modules are isolated test fixtures, not installed application features. The agent ships business frontend-design and idea-review skills, company identity intake and modal defaults. Real SMTP receipt/recovery and isolated offsite local/source-S3 attachment recovery are documented in the source repository's confirmed-achievements ledger. OAuth is optional and externally unverified. Source-S3 recovery is integrated into the operational backup commands and verified directly; local Docker backup/recovery also passed; natural scheduled operation and staging remain pending; each consumer must verify its own configuration.
 
-This is not the 1.0 capability catalog. Read docs/implementation-status.md before using a planned feature.
+This is not the 1.0 capability catalog. Planned features are listed in docs/implementation-status.md of the adula-kit source repository; do not assume them.
 
 Core user invitations are available through `UserInvitations` and the `core.users/invite` permission. New standalone projects include an Arabic invitation Dialog, SMTP mail and single-use 24-hour acceptance links; recipients set their own passwords and receive no automatic roles. Configure SMTP and APP_URL, then assign business roles after acceptance. Existing consumers must merge project-owned routes/pages deliberately.
 
 Administrative mutations protect the last active administrator and the acting administrator's own access. Repeated installation repairs missing bootstrap grants. The reference settings screen controls Gregorian, Umm al-Qura Hijri or dual-calendar presentation, edit-dialog dismissal confirmation and restrained transitions. Storage and API dates stay canonical. Permission actions require confirmation and report server outcomes.
 
-The separate @adula/create-app package creates a complete application from an empty directory, including local service provisioning, fresh migrations, an administrator and company identity intake. Node/npm and Docker for the default service mode are prerequisites; existing PostgreSQL/Redis can be used instead. The creator and kit remain unpublished; use local archives until an authorized release exists.
+The separate @adula/create-app package creates a complete application from an empty directory, including local service provisioning, fresh migrations, an administrator and company identity intake. Node/npm and Docker for the default service mode are prerequisites; existing PostgreSQL/Redis can be used instead. The packages are published on npm under the experimental `alpha` tag: `npm create @adula/app@alpha my-app`.

package/build/commands/gaps.js

@@ -6,6 +6,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { BaseCommand, args, flags } from '@adonisjs/core/ace';
 import { readFile } from 'node:fs/promises';
+import { gapReport } from '../src/commands/gap_report.js';
 /** Collects KIT_GAPS.md for reporting; nothing leaves the machine without explicit confirmation. */
 export default class Gaps extends BaseCommand {
     static commandName = 'adula:gaps';
@@ -22,14 +23,10 @@ export default class Gaps extends BaseCommand {
         catch {
             throw new Error('KIT_GAPS.md does not exist; adula:install creates it');
         }
-        const masked = content
-            .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, '<email>')
-            .replace(/https?:\/\/[^\s)]+/g, '<url>')
-            .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<ip>');
-        const gaps = masked.match(/^## GAP-\d+.*$/gm) ?? [];
-        this.logger.info(`${gaps.length} gap(s) recorded in KIT_GAPS.md`);
-        for (const title of gaps)
-            this.logger.log(`  ${title.replace(/^## /, '')}`);
+        const { masked, titles } = gapReport(content);
+        this.logger.info(`${titles.length} gap(s) recorded in KIT_GAPS.md`);
+        for (const title of titles)
+            this.logger.log(`  ${title}`);
         if (!this.yes) {
             const confirmed = await this.prompt.confirm('Show the full masked report? Nothing is sent anywhere by this command.');
             if (!confirmed)

package/build/commands/main.js

@@ -6,6 +6,7 @@ import ModuleAdd from './module_add.js';
 import ModuleRemove from './module_remove.js';
 import Ui from './ui.js';
 import StorageMigrate from './storage_migrate.js';
+import Gaps from './gaps.js';
 const commands = [
     Resource,
     Doctor,
@@ -15,6 +16,7 @@ const commands = [
     ModuleRemove,
     Ui,
     StorageMigrate,
+    Gaps,
 ];
 export async function getMetaData() {
     return commands.map((command) => {

package/build/index.d.ts

@@ -15,7 +15,7 @@ export { ResourceService } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
 export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
-export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, } from './src/attachments/attachment_service.js';
+export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, attachmentPolicy, pendingUploadCount, staleUploads, forgetUpload, DEFAULT_ATTACHMENT_EXTENSIONS, PENDING_UPLOAD_LIMIT, UNBOUND_UPLOAD_TTL_MS, } from './src/attachments/attachment_service.js';
 export type { AttachmentRecord, AttachmentSummary, UploadInput, ClaimInput, } from './src/attachments/attachment_service.js';
 export { migrateStorage } from './src/attachments/storage_migrate.js';
 export type { StorageDisk, StorageMigrationOptions, StorageMigrationResult, } from './src/attachments/storage_migrate.js';

package/build/index.js

@@ -11,7 +11,7 @@ export { ResourceService } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
 export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
-export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, } from './src/attachments/attachment_service.js';
+export { registerUpload, findAttachment, loadAttachments, claimAttachment, releaseAttachment, summarizeAttachment, attachmentUrl, isAttachmentId, isRelativeDiskPath, attachmentPolicy, pendingUploadCount, staleUploads, forgetUpload, DEFAULT_ATTACHMENT_EXTENSIONS, PENDING_UPLOAD_LIMIT, UNBOUND_UPLOAD_TTL_MS, } from './src/attachments/attachment_service.js';
 export { migrateStorage } from './src/attachments/storage_migrate.js';
 export { diagnoseAttachments } from './src/attachments/doctor.js';
 export { Settings, sequence, notify } from './src/services/settings.js';

package/build/src/admin/resource_service.d.ts

@@ -1,7 +1,7 @@
 import type { Knex } from 'knex';
 import type { ResourceRegistry } from '../resource/registry.js';
-import type { Action, RecordData, SerializedRecord } from '../resource/types.js';
-import { type Actor } from '../auth/ability.js';
+import type { Action, RecordData, Resource, SerializedRecord } from '../resource/types.js';
+import { type Actor, type KitAbility } from '../auth/ability.js';
 import type { ResourceDescription, ResourceNavigation, ResourceField } from './presentation.js';
 export type ListOptions = {
     limit?: number;
@@ -12,6 +12,11 @@ export type ListOptions = {
     filters?: Record<string, unknown>;
     estimate?: boolean;
 };
+/**
+ * Whether an actor may sort, filter or search by a field. Querying reveals values
+ * indirectly, so it needs unconditional view access at the field's level.
+ */
+export declare function canQueryField(resource: Resource, actor: Actor, ability: KitAbility, key: string): boolean;
 export declare class ResourceService {
     private db;
     private registry;
@@ -75,6 +80,11 @@ export declare class ResourceService {
         action: Action;
         fields: string[];
         actorId: number;
+        actorName: string | null;
+        /**
+         * @deprecated Always null. Kept so project-owned copies of resource-show from
+         * earlier releases still compile; they fall back to the actor id.
+         */
         actorEmail: string | null;
         createdAt: string;
     }[]>;
@@ -92,7 +102,21 @@ export declare class ResourceService {
             filterable?: boolean;
             permissionLevel?: number;
             sequence?: string;
-            type: "string" | "text" | "integer" | "money" | "boolean" | "date" | "datetime" | "json" | "attachment";
+            type: "string" | "text" | "integer" | "money" | "boolean" | "date" | "datetime" | "json";
+            key: string;
+        } | {
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "attachment";
+            accept?: string[] | "any";
+            maxSize?: string;
             key: string;
         } | {
             label: import("../resource/types.js").Label;

package/build/src/admin/resource_service.js

@@ -8,6 +8,19 @@ import { sequence } from '../services/settings.js';
 import { recordMutation } from '../events/record_mutation.js';
 import { fieldValue } from '../resource/values.js';
 import { claimAttachment, isAttachmentId, loadAttachments, releaseAttachment, } from '../attachments/attachment_service.js';
+/**
+ * Whether an actor may sort, filter or search by a field. Querying reveals values
+ * indirectly, so it needs unconditional view access at the field's level.
+ */
+export function canQueryField(resource, actor, ability, key) {
+    const level = Math.max(resource.fields[key].permissionLevel ?? 0, resource.hidden?.includes(key) ? 1 : 0);
+    // Conditional field rules cannot safely authorize a global sort/search.
+    return (actor.permissionLevel >= level &&
+        ability.can('view', resource.name, key) &&
+        !ability.rules.some((rule) => rule.conditions &&
+            (!rule.fields || rule.fields.includes(key)) &&
+            (rule.subject === resource.name || rule.subject === 'all')));
+}
 export class ResourceService {
     db;
     registry;
@@ -178,8 +191,9 @@ export class ResourceService {
             query.where(`r.${resource.fields[key].column ?? columnName(key)}`, value);
         }
         // Estimate the authorized, filtered query, never the deployment-wide table cardinality.
+        // Only the first page pays for the extra planner round trip; later pages keep its figure.
         let estimatedTotal;
-        if (options.estimate !== false) {
+        if (options.estimate !== false && !options.cursor) {
             const compiled = query.clone().clearSelect().select('r.id').toSQL();
             const estimate = await this.db.raw(`EXPLAIN (FORMAT JSON) ${compiled.sql}`, [
                 ...compiled.bindings,
@@ -242,13 +256,7 @@ export class ResourceService {
         };
     }
     canQueryField(resource, actor, ability, key) {
-        const level = Math.max(resource.fields[key].permissionLevel ?? 0, resource.hidden?.includes(key) ? 1 : 0);
-        // Conditional field rules cannot safely authorize a global sort/search.
-        return (actor.permissionLevel >= level &&
-            ability.can('view', resource.name, key) &&
-            !ability.rules.some((rule) => rule.conditions &&
-                (!rule.fields || rule.fields.includes(key)) &&
-                (rule.subject === resource.name || rule.subject === 'all')));
+        return canQueryField(resource, actor, ability, key);
     }
     async preload(resource, records, actor) {
         const related = {};
@@ -363,13 +371,19 @@ export class ResourceService {
             .where({ 'a.resource': name, 'a.record_id': id })
             .orderBy('a.id', 'desc')
             .limit(50)
-            .select('a.id', 'a.action', 'a.changes', 'a.actor_id', 'a.created_at', 'u.email as actor_email');
+            .select('a.id', 'a.action', 'a.changes', 'a.actor_id', 'a.created_at', 'u.full_name as actor_name');
         return rows.map((row) => ({
             id: Number(row.id),
             action: String(row.action),
             fields: Array.isArray(row.changes?.fields) ? row.changes.fields : [],
             actorId: Number(row.actor_id),
-            actorEmail: row.actor_email === null ? null : String(row.actor_email),
+            // A display name only: record viewers need not be able to read account e-mails.
+            actorName: row.actor_name ? String(row.actor_name) : null,
+            /**
+             * @deprecated Always null. Kept so project-owned copies of resource-show from
+             * earlier releases still compile; they fall back to the actor id.
+             */
+            actorEmail: null,
             createdAt: new Date(row.created_at).toISOString(),
         }));
     }
@@ -540,7 +554,12 @@ export class ResourceService {
                 candidate.orgPath = unit?.path;
             }
             this.requireRecord(ability, actor, resource, action, candidate);
-            for (const key of Object.keys(form)) {
+            // Validators may add fields (defaults, transforms); those are written too, so check them.
+            const written = new Set([
+                ...Object.keys(form),
+                ...Object.keys(validated).filter((key) => key in resource.fields),
+            ]);
+            for (const key of written) {
                 const field = resource.fields[key];
                 if (!ability.can(action, subject(name, candidate), key) ||
                     (id !== undefined && !ability.can(action, subject(name, existing), key)) ||
@@ -756,6 +775,7 @@ export class ResourceService {
             resource: resource.name,
             id: record.id,
             actorId: actor.id,
+            impersonatorId: actor.impersonatorId,
             action,
             fields,
         });

package/build/src/attachments/attachment_service.d.ts

@@ -1,5 +1,5 @@
 import type { Knex } from 'knex';
-import type { JsonValue } from '../resource/types.js';
+import type { Field, JsonValue } from '../resource/types.js';
 export type AttachmentSummary = {
     id: number;
     name: string;
@@ -51,6 +51,23 @@ export type ClaimInput = {
     orgUnitId?: number | null;
     scoped: boolean;
 };
+/** Business documents, images and archives; a field widens or narrows it with `accept`. */
+export declare const DEFAULT_ATTACHMENT_EXTENSIONS: readonly string[];
+/** Unbound uploads one user may hold at once; each is removed by pruning after a day. */
+export declare const PENDING_UPLOAD_LIMIT = 50;
+/** Uploads never bound to a record are removed after this age. */
+export declare const UNBOUND_UPLOAD_TTL_MS: number;
+/** Upload constraints of an attachment field: accepted extensions (undefined = any) and size. */
+export declare function attachmentPolicy(field: Field): {
+    extnames?: string[];
+    size: string;
+};
+/** Unbound uploads of one user; hosts refuse new uploads beyond PENDING_UPLOAD_LIMIT. */
+export declare function pendingUploadCount(db: Knex, userId: number): Promise<number>;
+/** Uploads that were never bound to a record and are older than the cutoff. */
+export declare function staleUploads(db: Knex, olderThan: Date, limit?: number): Promise<AttachmentRecord[]>;
+/** Deletes the row of an upload that is still unbound; the host removes the file first. */
+export declare function forgetUpload(db: Knex, id: number): Promise<boolean>;
 export declare function attachmentUrl(id: number): string;
 export declare function isAttachmentId(value: unknown): value is number;
 /** Disk keys stay relative and slash-separated so files move between disks unchanged. */

package/build/src/attachments/attachment_service.js

@@ -2,6 +2,68 @@ import { KitError } from '../admin/errors.js';
 import { identifier } from '../resource/define_resource.js';
 const MAX_ID = 2147483647;
 const REJECTED = 'المرفق غير موجود أو لا يخصك';
+/** Business documents, images and archives; a field widens or narrows it with `accept`. */
+export const DEFAULT_ATTACHMENT_EXTENSIONS = Object.freeze([
+    'pdf',
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'txt',
+    'csv',
+    'doc',
+    'docx',
+    'xls',
+    'xlsx',
+    'ppt',
+    'pptx',
+    'odt',
+    'ods',
+    'odp',
+    'rtf',
+    'zip',
+]);
+/** Unbound uploads one user may hold at once; each is removed by pruning after a day. */
+export const PENDING_UPLOAD_LIMIT = 50;
+/** Uploads never bound to a record are removed after this age. */
+export const UNBOUND_UPLOAD_TTL_MS = 24 * 60 * 60 * 1000;
+/** Upload constraints of an attachment field: accepted extensions (undefined = any) and size. */
+export function attachmentPolicy(field) {
+    if (field.type !== 'attachment')
+        throw new KitError(422, 'E_FIELD_INVALID', 'الحقل ليس حقل مرفقات');
+    const accept = field.accept ?? DEFAULT_ATTACHMENT_EXTENSIONS;
+    return {
+        extnames: accept === 'any'
+            ? undefined
+            : accept.map((extname) => extname.toLowerCase().replace(/^\./, '')),
+        size: field.maxSize ?? '20mb',
+    };
+}
+/** Unbound uploads of one user; hosts refuse new uploads beyond PENDING_UPLOAD_LIMIT. */
+export async function pendingUploadCount(db, userId) {
+    const [{ count }] = await db('attachments')
+        .where('uploaded_by', userId)
+        .whereNull('record_id')
+        .whereNull('deleted_at')
+        .count('* as count');
+    return Number(count);
+}
+/** Uploads that were never bound to a record and are older than the cutoff. */
+export async function staleUploads(db, olderThan, limit = 500) {
+    const rows = await db('attachments')
+        .whereNull('record_id')
+        .where('created_at', '<', olderThan)
+        .orderBy('id')
+        .limit(limit);
+    return rows.map(fromRow);
+}
+/** Deletes the row of an upload that is still unbound; the host removes the file first. */
+export async function forgetUpload(db, id) {
+    if (!isAttachmentId(id))
+        return false;
+    return (await db('attachments').where('id', id).whereNull('record_id').delete()) > 0;
+}
 export function attachmentUrl(id) {
     return `/attachments/${id}`;
 }

package/build/src/auth/ability.d.ts

@@ -13,6 +13,8 @@ export type Actor = {
     orgPaths: string[];
     permissionLevel: number;
     rules: Rule[];
+    /** Set while an administrator acts as this user; recorded with every mutation. */
+    impersonatorId?: number;
 };
 export type KitAbility = Ability<[string, any], Conditions>;
 export declare const abilitySchemas: WeakMap<KitAbility, readonly Pick<Resource, "fields" | "name">[]>;

package/build/src/commands/gap_report.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Prepares KIT_GAPS.md for sharing with the kit maintainers: e-mails, URLs and
+ * IPv4 addresses are masked, and gap titles are listed for a quick review.
+ */
+export declare function gapReport(content: string): {
+    masked: string;
+    titles: string[];
+};

package/build/src/commands/gap_report.js

@@ -0,0 +1,12 @@
+/**
+ * Prepares KIT_GAPS.md for sharing with the kit maintainers: e-mails, URLs and
+ * IPv4 addresses are masked, and gap titles are listed for a quick review.
+ */
+export function gapReport(content) {
+    const masked = content
+        .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, '<email>')
+        .replace(/https?:\/\/[^\s)]+/g, '<url>')
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<ip>');
+    const titles = (masked.match(/^## GAP-\d+.*$/gm) ?? []).map((title) => title.replace(/^## /, ''));
+    return { masked, titles };
+}

package/build/src/core/saved_views.js

@@ -1,7 +1,10 @@
 import { buildAbility } from '../auth/ability.js';
 import { KitError } from '../admin/errors.js';
+import { canQueryField } from '../admin/resource_service.js';
 const NAME_LIMIT = 60;
 const VIEW_LIMIT = 50;
+/** Shared views are visible to every viewer of a resource; cap them per resource. */
+const SHARED_LIMIT = 100;
 /**
  * A saved view is stored user input that later drives a list query, so every key
  * is validated against the resource definition before it is written and again
@@ -16,12 +19,14 @@ export class SavedViews {
         this.registry = registry;
     }
     async list(name, actor) {
-        const resource = this.authorize(name, actor);
+        const { resource } = this.authorize(name, actor);
+        // Own views first, so colleagues' shared views can never crowd them out.
         const rows = await this.db('saved_views')
             .where('resource', resource.name)
             .where((where) => where.where('user_id', actor.id).orWhere('shared', true))
+            .orderByRaw('(user_id = ?) DESC', [actor.id])
             .orderBy('name')
-            .limit(VIEW_LIMIT * 2);
+            .limit(VIEW_LIMIT + SHARED_LIMIT);
         return rows.flatMap((row) => {
             const query = this.sanitize(resource, row.query);
             return query
@@ -38,15 +43,35 @@ export class SavedViews {
         });
     }
     async save(name, actor, input) {
-        const resource = this.authorize(name, actor);
+        const { resource, ability } = this.authorize(name, actor);
         const label = typeof input.name === 'string' ? input.name.trim() : '';
         if (!label || label.length > NAME_LIMIT)
             throw new KitError(422, 'E_VIEW_NAME', 'اسم العرض مطلوب ولا يتجاوز 60 حرفاً');
         const query = this.sanitize(resource, input.query, true);
+        // A view may only query what its author may query; stored filters must not probe hidden fields.
+        const queried = [
+            ...(query.sort ? [query.sort] : []),
+            ...Object.keys(query.filters ?? {}),
+            ...(query.search
+                ? Object.entries(resource.fields)
+                    .filter(([, field]) => field.searchable)
+                    .map(([key]) => key)
+                : []),
+        ];
+        for (const key of queried)
+            if (!canQueryField(resource, actor, ability, key))
+                throw new KitError(403, 'E_FIELD_FORBIDDEN', `لا يمكنك الاستعلام بهذا الحقل: ${key}`);
         const shared = input.shared === true;
         const existing = await this.db('saved_views')
             .where({ user_id: actor.id, resource: resource.name, name: label })
-            .first('id');
+            .first('id', 'shared');
+        if (shared && !existing?.shared) {
+            const [{ count }] = await this.db('saved_views')
+                .where({ resource: resource.name, shared: true })
+                .count('* as count');
+            if (Number(count) >= SHARED_LIMIT)
+                throw new KitError(422, 'E_VIEW_LIMIT', 'بلغ هذا الكيان الحد الأقصى للعروض المشتركة');
+        }
         if (!existing) {
             const [{ count }] = await this.db('saved_views')
                 .where({ user_id: actor.id, resource: resource.name })
@@ -68,7 +93,7 @@ export class SavedViews {
         return { id: Number(row.id), name: label, query, shared, own: true };
     }
     async remove(name, actor, id) {
-        const resource = this.authorize(name, actor);
+        const { resource } = this.authorize(name, actor);
         const removed = await this.db('saved_views')
             .where({ id, resource: resource.name, user_id: actor.id })
             .del();
@@ -80,7 +105,7 @@ export class SavedViews {
         const ability = buildAbility(actor.rules, this.registry.all());
         if (!resource.actions.includes('view') || !ability.can('view', resource.name))
             throw new KitError(403, 'E_FORBIDDEN', 'ليس لديك صلاحية لهذا الكيان');
-        return resource;
+        return { resource, ability };
     }
     /** Returns null for a stored view the resource no longer supports; throws on user input. */
     sanitize(resource, value, strict = false) {

package/build/src/core/user_invitations.js

@@ -104,8 +104,8 @@ export class UserInvitations {
     async accept(token, password, hashPassword) {
         if (!(await this.valid(token)))
             throw invalid();
-        if (typeof password !== 'string' || password.length < 8 || password.length > 32)
-            throw new KitError(422, 'E_PASSWORD', 'كلمة المرور من 8 إلى 32 حرفًا');
+        if (typeof password !== 'string' || password.length < 8 || password.length > 64)
+            throw new KitError(422, 'E_PASSWORD', 'كلمة المرور من 8 إلى 64 حرفًا');
         const passwordHash = await hashPassword(password);
         return this.db.transaction(async (trx) => {
             const pending = await trx('user_invitations').where('token_hash', digest(token)).first();

package/build/src/events/record_mutation.d.ts

@@ -6,6 +6,8 @@ export declare function recordMutation(trx: Knex.Transaction, mutation: {
     resource: string;
     id: unknown;
     actorId: number;
+    /** The administrator acting as actorId, when impersonating. */
+    impersonatorId?: number;
     action: Action;
     fields: string[];
 }): Promise<void>;

package/build/src/events/record_mutation.js

@@ -17,13 +17,17 @@ export async function recordMutation(trx, mutation) {
         resource: mutation.resource,
         id: mutation.id,
         actorId: mutation.actorId,
+        ...(mutation.impersonatorId ? { impersonatorId: mutation.impersonatorId } : {}),
     };
     await trx('activities').insert({
         resource: mutation.resource,
         record_id: mutation.id,
         actor_id: mutation.actorId,
         action: mutation.action,
-        changes: JSON.stringify({ fields: mutation.fields }),
+        changes: JSON.stringify({
+            fields: mutation.fields,
+            ...(mutation.impersonatorId ? { impersonatedBy: mutation.impersonatorId } : {}),
+        }),
     });
     await trx('outbox').insert({
         id: eventId,

package/build/src/resource/types.d.ts

@@ -22,7 +22,16 @@ export type Field = {
     permissionLevel?: number;
     sequence?: string;
 } & ({
-    type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json' | 'attachment';
+    type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json';
+} | {
+    type: 'attachment';
+    /**
+     * Lower-case file extensions accepted for upload, or 'any'. Defaults to
+     * DEFAULT_ATTACHMENT_EXTENSIONS (documents, images and archives).
+     */
+    accept?: string[] | 'any';
+    /** Upload size limit such as '5mb'. Defaults to '20mb'. */
+    maxSize?: string;
 } | {
     type: 'belongsTo';
     resource: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adula/kit",
   "description": "Resource-driven business applications for AdonisJS 7",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.4",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -45,7 +45,6 @@
     "@jrmc/adonis-mcp": "2.0.0",
     "@poppinss/ts-exec": "1.4.4",
     "@types/node": "26.2.0",
-    "@ucast/sql": "0.2.0",
     "eslint": "10.9.0",
     "pg": "8.16.3",
     "typescript": "6.0.3"
@@ -72,15 +71,6 @@
     "access": "public",
     "provenance": true
   },
-  "c8": {
-    "reporter": [
-      "text",
-      "html"
-    ],
-    "exclude": [
-      "tests/**"
-    ]
-  },
   "prettier": "@adonisjs/prettier-config",
   "dependencies": {
     "@casl/ability": "7.0.1",