@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/admin/resource_service.js

@@ -2,12 +2,19 @@ import { subject } from '@casl/ability';
 import { columnName } from '../resource/define_resource.js';
 import { buildAbility, canRecord, inOrgScope, } from '../auth/ability.js';
 import { accessibleBy, conditionSql } from '../auth/sql.js';
-import { fromRow, selectedFields, serialize, writableInput } from './contracts.js';
+import { fromRow, jsonValue, selectedFields, serialize, systemInput, writableInput, } from './contracts.js';
+import { resolveActorConditions } from '../auth/conditions.js';
 import { KitError } from './errors.js';
 import { sequence } from '../services/settings.js';
 import { recordMutation } from '../events/record_mutation.js';
+import { formatTitle, titleFields } from './record_title.js';
 import { fieldValue } from '../resource/values.js';
 import { claimAttachment, isAttachmentId, loadAttachments, releaseAttachment, } from '../attachments/attachment_service.js';
+/** Per-process cache of planner row estimates for identical list queries. */
+const estimates = new Map();
+const ESTIMATE_TTL_MS = 30_000;
+const ESTIMATE_CACHE_LIMIT = 500;
+const AGGREGATE_GROUP_LIMIT = 1000;
 /**
  * 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.
@@ -28,6 +35,10 @@ export class ResourceService {
         this.db = db;
         this.registry = registry;
     }
+    /** The Arabic label of a registered resource, for notifications and titles. */
+    label(name) {
+        return this.registry.get(name).label.ar;
+    }
     /** Project navigation is derived from registered resources and the current actor. */
     navigation(actor) {
         const ability = buildAbility(actor.rules, this.registry.all());
@@ -45,6 +56,10 @@ export class ResourceService {
             label: resource.label.ar,
             href: `/resources/${resource.name}`,
             module: this.registry.owner(resource.name),
+            moduleLabel: this.registry
+                .modules()
+                .find((module) => module.name === this.registry.owner(resource.name))?.label.ar ??
+                this.registry.owner(resource.name),
         }));
     }
     describe(name, actor) {
@@ -67,6 +82,8 @@ export class ResourceService {
         return {
             name,
             label: resource.label.ar,
+            recordLabel: resource.recordLabel?.ar ?? null,
+            createLabel: resource.createLabel?.ar ?? null,
             fields,
             list: resource.list.filter((key) => visible.has(key)),
             show: resource.show.filter((key) => visible.has(key)),
@@ -85,7 +102,7 @@ export class ResourceService {
                     !['update', 'delete', 'submit'].includes(action) ||
                     record.docStatus === 0) &&
                 (action !== 'cancel' || (resource.submittable && record.docStatus === 1)) &&
-                action !== 'amend',
+                (action !== 'amend' || (resource.submittable && record.docStatus === 2)),
         ]));
     }
     normalizeValues(resource, record) {
@@ -154,12 +171,56 @@ export class ResourceService {
             throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
         return fromRow(row, resource);
     }
+    /** A live record regardless of any actor's scope, for system writes. */
+    async findAny(db, resource, id, lock = false) {
+        const query = db(`${resource.name} as r`).whereNull('r.deleted_at').where('r.id', id);
+        query.select(selectedFields(resource, buildAbility([], []), { write: true }).map((key) => `r.${resource.fields[key]?.column ?? columnName(key)}`));
+        if (resource.scoped)
+            query.leftJoin('org_units as ou', 'ou.id', 'r.org_unit_id').select('ou.path as org_path');
+        if (lock)
+            query.forUpdate('r');
+        const row = await query.first();
+        if (!row)
+            throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
+        return fromRow(row, resource);
+    }
     requireRecord(ability, actor, resource, action, record) {
         if (resource.scoped && !inOrgScope(record.orgPath, actor.orgPaths))
             throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
         if (!canRecord(ability, actor, resource, action, record))
             throw new KitError(403, 'E_FORBIDDEN', 'ليس لديك صلاحية لهذا الإجراء');
     }
+    /**
+     * Authorizes one record for collaboration features (comments, tags, assignments...).
+     * Scope and conditional rules apply exactly as for show/update.
+     */
+    async access(name, id, actor, action = 'view', db = this.db) {
+        let resource;
+        try {
+            resource = this.registry.get(name);
+        }
+        catch {
+            throw new KitError(404, 'E_NOT_FOUND', 'الكيان غير موجود');
+        }
+        if (!Number.isSafeInteger(id) || id <= 0)
+            throw new KitError(404, 'E_NOT_FOUND', 'السجل غير موجود');
+        const ability = this.authorizeAction(resource, actor, action);
+        const record = await this.find(db, resource, actor, ability, id);
+        this.requireRecord(ability, actor, resource, action, record);
+        return { resource, record, ability };
+    }
+    /** Whether a (possibly other) actor may perform an action on a record; never throws for denial. */
+    async permits(name, id, actor, action = 'view') {
+        try {
+            await this.access(name, id, actor, action);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof KitError && [403, 404].includes(error.status))
+                return false;
+            throw error;
+        }
+    }
     async list(name, actor, options = {}) {
         const resource = this.registry.get(name);
         const ability = this.authorizeAction(resource, actor, 'view');
@@ -190,15 +251,36 @@ export class ResourceService {
                 throw new KitError(422, 'E_FILTER', 'Invalid filter value');
             query.where(`r.${resource.fields[key].column ?? columnName(key)}`, value);
         }
+        if (options.tag !== undefined && options.tag !== null && options.tag !== '') {
+            if (typeof options.tag !== 'string' || options.tag.length > 60)
+                throw new KitError(422, 'E_FILTER', 'Invalid tag filter');
+            query.whereExists((exists) => exists
+                .from('taggables as tg')
+                .join('tags as tn', 'tn.id', 'tg.tag_id')
+                .where('tg.resource', name)
+                .whereRaw('tg.record_id = r.id')
+                .where('tn.name', options.tag));
+        }
         // 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 && !options.cursor) {
             const compiled = query.clone().clearSelect().select('r.id').toSQL();
-            const estimate = await this.db.raw(`EXPLAIN (FORMAT JSON) ${compiled.sql}`, [
-                ...compiled.bindings,
-            ]);
-            estimatedTotal = Number(estimate.rows[0]['QUERY PLAN'][0].Plan['Plan Rows']);
+            // The planner estimate is approximate by nature; reuse it briefly for the same
+            // authorized, filtered query instead of planning it on every first page.
+            const key = `${compiled.sql}\u0000${JSON.stringify(compiled.bindings)}`;
+            const cached = estimates.get(key);
+            if (cached && cached.at > Date.now() - ESTIMATE_TTL_MS)
+                estimatedTotal = cached.rows;
+            else {
+                const estimate = await this.db.raw(`EXPLAIN (FORMAT JSON) ${compiled.sql}`, [
+                    ...compiled.bindings,
+                ]);
+                estimatedTotal = Number(estimate.rows[0]['QUERY PLAN'][0].Plan['Plan Rows']);
+                if (estimates.size >= ESTIMATE_CACHE_LIMIT)
+                    estimates.delete(estimates.keys().next().value);
+                estimates.set(key, { rows: estimatedTotal, at: Date.now() });
+            }
         }
         if (options.cursor) {
             let cursor;
@@ -258,10 +340,128 @@ export class ResourceService {
     canQueryField(resource, actor, ability, key) {
         return canQueryField(resource, actor, ability, key);
     }
+    /**
+     * Counts and totals over the records the actor may view, grouped by queryable fields,
+     * for dashboards. Authorization is list()'s: the same rules, organization scope and
+     * soft-delete filter apply, and every grouped, totalled or filtered field must be one
+     * the actor may query (E_FIELD_FORBIDDEN otherwise), so no hidden value leaks.
+     */
+    async aggregate(name, actor, options = {}) {
+        const resource = this.registry.get(name);
+        const ability = this.authorizeAction(resource, actor, 'view');
+        const standard = new Set([
+            ...(resource.submittable ? ['docStatus'] : []),
+            ...(resource.scoped ? ['orgUnitId'] : []),
+        ]);
+        const column = (key) => `r.${resource.fields[key]?.column ?? columnName(key)}`;
+        const queryable = (key, kinds) => {
+            if (typeof key !== 'string')
+                return false;
+            if (standard.has(key))
+                return !kinds;
+            // Own keys only: names such as "constructor" are not fields.
+            if (!Object.hasOwn(resource.fields, key))
+                return false;
+            const field = resource.fields[key];
+            return (Boolean(field) &&
+                !['hasMany', 'json', 'attachment'].includes(field.type) &&
+                (!kinds || kinds.includes(field.type)) &&
+                this.canQueryField(resource, actor, ability, key));
+        };
+        const groupBy = options.groupBy ?? [];
+        const sums = options.sum ?? [];
+        if (!Array.isArray(groupBy) || groupBy.length > 3 || !Array.isArray(sums) || sums.length > 5)
+            throw new KitError(422, 'E_AGGREGATE', 'Group by up to three fields and total up to five');
+        for (const key of groupBy)
+            if (!queryable(key))
+                throw new KitError(403, 'E_FIELD_FORBIDDEN', `Field cannot be grouped: ${String(key)}`);
+        for (const key of sums)
+            if (!queryable(key, ['integer', 'money']))
+                throw new KitError(403, 'E_FIELD_FORBIDDEN', `Field cannot be totalled: ${String(key)}`);
+        const query = accessibleBy(this.db(`${name} as r`).whereNull('r.deleted_at'), ability, actor, 'view', resource);
+        for (const [key, value] of Object.entries(options.filters ?? {})) {
+            if (!resource.fields[key]?.filterable || !queryable(key))
+                throw new KitError(422, 'E_FILTER', 'Unsupported filter');
+            if (value !== null && !['string', 'number', 'boolean'].includes(typeof value))
+                throw new KitError(422, 'E_FILTER', 'Invalid filter value');
+            query.where(column(key), value);
+        }
+        if (options.where !== undefined && options.where !== null) {
+            if (typeof options.where !== 'object' || Array.isArray(options.where))
+                throw new KitError(422, 'E_FILTER', 'Conditions must be an object');
+            for (const key of Object.keys(options.where))
+                if (!queryable(key))
+                    throw new KitError(403, 'E_FIELD_FORBIDDEN', `Field cannot be filtered: ${key}`);
+            let where;
+            try {
+                where = conditionSql(resolveActorConditions(options.where, actor.id), resource);
+            }
+            catch (error) {
+                throw new KitError(422, 'E_FILTER', error.message);
+            }
+            query.whereRaw(where.text, where.bindings);
+        }
+        if (options.search) {
+            const searchable = Object.entries(resource.fields).filter(([, f]) => f.searchable);
+            if (!searchable.length || searchable.some(([key]) => !queryable(key)))
+                throw new KitError(403, 'E_SEARCH', 'Search is unavailable');
+            query.whereRaw("r.search_vector @@ plainto_tsquery('simple', ?)", [options.search]);
+        }
+        const selects = groupBy.map((key, index) => `${key === 'docStatus' ? 'r.doc_status' : column(key)} as g${index}`);
+        if (options.count !== false)
+            selects.push(this.db.raw('count(*)::int as count'));
+        sums.forEach((key, index) => selects.push(this.db.raw(`sum(??)::text as s${index}`, [column(key)])));
+        query.select(selects);
+        groupBy.forEach((_, index) => query.groupByRaw(`${index + 1}`));
+        groupBy.forEach((_, index) => query.orderByRaw(`${index + 1} ASC NULLS LAST`));
+        const rows = await query.limit(AGGREGATE_GROUP_LIMIT + 1);
+        return {
+            truncated: rows.length > AGGREGATE_GROUP_LIMIT,
+            rows: rows.slice(0, AGGREGATE_GROUP_LIMIT).map((row) => {
+                const group = fromRow(Object.fromEntries(groupBy.map((key, index) => [
+                    key === 'docStatus'
+                        ? 'doc_status'
+                        : key === 'orgUnitId'
+                            ? 'org_unit_id'
+                            : (resource.fields[key].column ?? columnName(key)),
+                    row[`g${index}`],
+                ])), resource);
+                return {
+                    group: Object.fromEntries(groupBy.map((key) => [key, jsonValue(group[key])])),
+                    ...(options.count !== false ? { count: Number(row.count) } : {}),
+                    ...(sums.length
+                        ? {
+                            sum: Object.fromEntries(sums.map((key, index) => [
+                                key,
+                                row[`s${index}`] === null ? null : String(row[`s${index}`]),
+                            ])),
+                        }
+                        : {}),
+                };
+            }),
+        };
+    }
     async preload(resource, records, actor) {
         const related = {};
         const ability = buildAbility(actor.rules, this.registry.all());
         for (const [key, field] of Object.entries(resource.fields)) {
+            if (field.type === 'user' && records.length) {
+                const ids = records
+                    .filter((record) => key in serialize(resource, record, ability, actor))
+                    .map((record) => record[key])
+                    .filter((v) => v !== null && v !== undefined);
+                // A display name only: readers of the record need not read account e-mails.
+                if (ids.length) {
+                    const users = await this.db('users')
+                        .whereIn('id', [...new Set(ids)])
+                        .select('id', 'full_name');
+                    related[key] = users.map((row) => ({
+                        id: Number(row.id),
+                        fullName: String(row.full_name ?? ''),
+                    }));
+                }
+                continue;
+            }
             if (field.type !== 'belongsTo' || !records.length)
                 continue;
             const target = this.registry.get(field.resource);
@@ -278,10 +478,61 @@ export class ResourceService {
                 query.select('ou.path as org_path');
             const rows = await query;
             const targets = await this.hydrate(this.db, target, rows.map((r) => fromRow(r, target)));
-            related[key] = targets.map((r) => serialize(target, r, ability, actor));
+            const title = await this.titler(target);
+            related[key] = targets.map((r) => {
+                const row = serialize(target, r, ability, actor);
+                // `_title` cannot collide with a field key; clients label the relation with it.
+                return { ...row, _title: title(row) };
+            });
         }
         return related;
     }
+    /** Formats record titles of one resource, loading the labels of its title lookups once. */
+    async titler(resource) {
+        const groups = titleFields(resource).flatMap((key) => {
+            const field = resource.fields[key];
+            return field.type === 'lookup' ? [field.group] : [];
+        });
+        const labels = new Map();
+        if (groups.length)
+            for (const row of await this.db('lookups')
+                .whereIn('group', groups)
+                .select('group', 'key', 'label_ar'))
+                labels.set(`${row.group}\u0000${row.key}`, String(row.label_ar));
+        return (record) => formatTitle(resource, record, (group, key) => labels.get(`${group}\u0000${key}`));
+    }
+    /**
+     * Titles of records the actor may view, read under the actor's field access (#32).
+     * Records the actor cannot view are left out; callers fall back to the record id.
+     */
+    async titles(name, ids, actor) {
+        const result = new Map();
+        let resource;
+        try {
+            resource = this.registry.get(name);
+        }
+        catch {
+            return result;
+        }
+        const wanted = [...new Set(ids.filter((id) => Number.isSafeInteger(id) && id > 0))];
+        const ability = buildAbility(actor.rules, this.registry.all());
+        if (!wanted.length || !resource.actions.includes('view') || !ability.can('view', name))
+            return result;
+        const query = accessibleBy(this.db(`${resource.name} as r`).whereIn('r.id', wanted).whereNull('r.deleted_at'), ability, actor, 'view', resource).select(this.columns(resource, ability));
+        if (resource.scoped)
+            query.select('ou.path as org_path');
+        const rows = await query;
+        const records = rows.map((row) => fromRow(row, resource));
+        const title = await this.titler(resource);
+        for (const record of records) {
+            if (!canRecord(ability, actor, resource, 'view', record))
+                continue;
+            const text = title(serialize(resource, record, ability, actor));
+            if (text)
+                result.set(Number(record.id), text);
+        }
+        return result;
+    }
     async show(name, id, actor) {
         const resource = this.registry.get(name);
         const ability = this.authorizeAction(resource, actor, 'view');
@@ -295,6 +546,8 @@ export class ResourceService {
         };
     }
     async relationOptions(name, key, actor, options = {}) {
+        if (this.registry.get(name).fields[key]?.type === 'user')
+            return this.userOptions(name, key, actor, options);
         const editor = await this.editor(name, actor, options.id);
         const field = editor.fields.find((entry) => entry.key === key);
         if (!field || field.type !== 'belongsTo')
@@ -306,20 +559,107 @@ export class ResourceService {
             limit: 50,
             estimate: false,
         });
+        const title = await this.titler(target);
         return {
             data: page.data.map((row) => ({
                 value: String(row.id),
-                label: String(row[target.list[0]] ?? row.id),
+                label: title(row) ?? `#${row.id}`,
             })),
             nextCursor: page.meta.nextCursor,
         };
     }
+    /**
+     * Choices for a user field. A form lists active members of the record's unit or its
+     * ancestors (the users the record is visible to through membership); a filter lists
+     * active users who share organization scope with the actor. Only names are returned.
+     */
+    async userOptions(name, key, actor, options) {
+        const resource = this.registry.get(name);
+        let path = null;
+        if (options.purpose === 'filter') {
+            const field = this.describe(name, actor).fields.find((entry) => entry.key === key);
+            if (!field?.filterable)
+                throw new KitError(403, 'E_FIELD_FORBIDDEN', 'ليس لديك صلاحية لهذا الحقل');
+        }
+        else {
+            const editor = await this.editor(name, actor, options.id);
+            if (!editor.fields.some((entry) => entry.key === key))
+                throw new KitError(403, 'E_FIELD_FORBIDDEN', 'ليس لديك صلاحية لهذا الحقل');
+            if (resource.scoped) {
+                const unit = options.orgUnitId ??
+                    (editor.record?.orgUnitId === undefined ? undefined : Number(editor.record.orgUnitId));
+                // Without a unit (for example an inline row) the choices follow the actor's scope;
+                // saving still checks the record's unit.
+                if (unit !== undefined) {
+                    const row = await this.db('org_units').where('id', unit).first('path');
+                    // Only units the actor works in (or the record's current unit) may be probed.
+                    if (!row ||
+                        (!inOrgScope(row.path, actor.orgPaths) &&
+                            Number(unit) !== Number(editor.record?.orgUnitId)))
+                        return { data: [], nextCursor: null };
+                    path = String(row.path);
+                }
+            }
+        }
+        let after = 0;
+        if (options.cursor !== undefined && options.cursor !== '') {
+            after = Number(options.cursor);
+            if (!Number.isSafeInteger(after) || after < 0)
+                throw new KitError(422, 'E_CURSOR', 'Invalid cursor');
+        }
+        const query = this.eligibleUsers(this.db, path, actor)
+            .where('u.id', '>', after)
+            .orderBy('u.id')
+            .limit(51)
+            .select('u.id', 'u.full_name');
+        if (options.search)
+            query.whereILike('u.full_name', `%${options.search.replace(/[\\%_]/g, '\\$&')}%`);
+        const rows = await query;
+        return {
+            data: rows.slice(0, 50).map((row) => ({
+                value: String(row.id),
+                label: String(row.full_name || `#${row.id}`),
+            })),
+            nextCursor: rows.length > 50 ? String(rows[49].id) : null,
+        };
+    }
+    /**
+     * Active users eligible for a user field: members of the unit at `path` or of one of
+     * its ancestors, or (without a path) users sharing organization scope with the actor.
+     * A system write on an unscoped resource passes no actor: any active member qualifies.
+     */
+    eligibleUsers(db, path, actor) {
+        return db('users as u')
+            .whereNull('u.disabled_at')
+            .whereExists((members) => {
+            members
+                .from('user_org_units as m')
+                .join('org_units as o', 'o.id', 'm.org_unit_id')
+                .whereRaw('m.user_id = u.id');
+            if (path !== null)
+                members.whereRaw('?::ltree <@ o.path', [path]);
+            else if (actor)
+                members.where((scope) => {
+                    if (!actor.orgPaths.length)
+                        scope.whereRaw('FALSE');
+                    for (const own of actor.orgPaths)
+                        scope.orWhereRaw('o.path <@ ?::ltree', [own]).orWhereRaw('o.path @> ?::ltree', [own]);
+                });
+        })
+            .distinct();
+    }
     /** Deferred relation reads re-authorize the parent and each child on every request. */
     async children(name, id, actor) {
         const resource = this.registry.get(name);
         const ability = this.authorizeAction(resource, actor, 'view');
         const parent = await this.find(this.db, resource, actor, ability, id);
         this.requireRecord(ability, actor, resource, 'view', parent);
+        return this.childrenOf(resource, parent, actor, ability);
+    }
+    /** Inline children of an already authorized parent record. */
+    async childrenOf(resource, parent, actor, ability) {
+        const name = resource.name;
+        const id = Number(parent.id);
         const result = {};
         for (const key of resource.show) {
             const field = resource.fields[key];
@@ -366,6 +706,38 @@ export class ResourceService {
         const ability = this.authorizeAction(resource, actor, 'view');
         const record = await this.find(this.db, resource, actor, ability, id);
         this.requireRecord(ability, actor, resource, 'view', record);
+        return this.activityOf(name, id);
+    }
+    /**
+     * Inline children and recent activity of one record, authorized with a single record
+     * read (for deferred page props that would otherwise read the record twice).
+     */
+    async details(name, id, actor) {
+        const resource = this.registry.get(name);
+        const ability = this.authorizeAction(resource, actor, 'view');
+        const record = await this.find(this.db, resource, actor, ability, id);
+        this.requireRecord(ability, actor, resource, 'view', record);
+        return {
+            children: await this.childrenOf(resource, record, actor, ability),
+            activity: await this.activityOf(name, id),
+        };
+    }
+    /** show(), children() and activity() of one record from a single record read. */
+    async record(name, id, actor) {
+        const resource = this.registry.get(name);
+        const ability = this.authorizeAction(resource, actor, 'view');
+        const record = await this.find(this.db, resource, actor, ability, id);
+        this.requireRecord(ability, actor, resource, 'view', record);
+        const [hydrated] = await this.hydrate(this.db, resource, [record]);
+        return {
+            data: serialize(resource, hydrated, ability, actor),
+            permissions: this.permissions(resource, record, actor, ability),
+            related: await this.preload(resource, [record], actor),
+            children: await this.childrenOf(resource, record, actor, ability),
+            activity: await this.activityOf(name, id),
+        };
+    }
+    async activityOf(name, id) {
         const rows = await this.db('activities as a')
             .leftJoin('users as u', 'u.id', 'a.actor_id')
             .where({ 'a.resource': name, 'a.record_id': id })
@@ -387,7 +759,13 @@ export class ResourceService {
             createdAt: new Date(row.created_at).toISOString(),
         }));
     }
-    async editor(name, actor, id) {
+    /**
+     * The form description for create (no id) or update. `defaults` pre-fills a create form
+     * (#48), for example `?defaults[violation]=13`: only visible form fields are used, a
+     * related record must be viewable by the actor and a lookup must be active. Anything else
+     * is dropped. Defaults are only initial values; saving validates as usual.
+     */
+    async editor(name, actor, id, request = {}) {
         const resource = this.registry.get(name);
         const action = id === undefined ? 'create' : 'update';
         const ability = this.authorizeAction(resource, actor, action);
@@ -461,9 +839,10 @@ export class ResourceService {
                 if (ability.can('view', target.name)) {
                     relationSearch[field.key] = this.describe(target.name, actor).searchable;
                     const page = await this.list(target.name, actor, { limit: 50, estimate: false });
+                    const title = await this.titler(target);
                     options[field.key] = page.data.map((row) => ({
                         value: String(row.id),
-                        label: String(row[target.list[0]] ?? row.id),
+                        label: title(row) ?? `#${row.id}`,
                     }));
                     const selected = record?.[field.key];
                     if (selected !== null &&
@@ -473,7 +852,7 @@ export class ResourceService {
                             const current = await this.show(target.name, Number(selected), actor);
                             options[field.key].push({
                                 value: String(current.data.id),
-                                label: String(current.data[target.list[0]] ?? current.data.id),
+                                label: title(current.data) ?? `#${current.data.id}`,
                             });
                         }
                         catch (error) {
@@ -485,8 +864,24 @@ export class ResourceService {
                 else
                     options[field.key] = [];
             }
+            else if (field.type === 'user') {
+                // Choices depend on the unit chosen in the form; they load from relationOptions.
+                relationSearch[field.key] = true;
+                options[field.key] = [];
+                const selected = record?.[field.key];
+                if (selected !== null && selected !== undefined) {
+                    const current = await this.db('users')
+                        .where('id', Number(selected))
+                        .first('id', 'full_name');
+                    if (current)
+                        options[field.key].push({
+                            value: String(current.id),
+                            label: String(current.full_name || `#${current.id}`),
+                        });
+                }
+            }
         }
-        const units = resource.scoped
+        const units = resource.scoped && !resource.scope
             ? await this.db('org_units')
                 .where((query) => {
                 if (!actor.orgPaths.length)
@@ -505,16 +900,78 @@ export class ResourceService {
             if (current)
                 units.push(current);
         }
+        const defaults = {};
+        const requested = request.defaults;
+        if (id === undefined && requested && typeof requested === 'object')
+            for (const field of fields) {
+                const raw = Object.hasOwn(requested, field.key) ? requested[field.key] : undefined;
+                if (typeof raw !== 'string' && typeof raw !== 'number' && typeof raw !== 'boolean')
+                    continue;
+                let value = raw;
+                try {
+                    if (['integer', 'belongsTo', 'user'].includes(field.type))
+                        value = Number(raw);
+                    else if (field.type === 'boolean')
+                        value = raw === true || raw === 'true';
+                    else
+                        value = String(raw);
+                    value = fieldValue(field, value);
+                }
+                catch {
+                    continue;
+                }
+                if (['attachment', 'json', 'hasMany'].includes(field.type))
+                    continue;
+                if (field.type === 'user') {
+                    // The unit is chosen later in the form; saving checks the record's unit.
+                    const user = await this.eligibleUsers(this.db, null, actor)
+                        .where('u.id', Number(value))
+                        .first('u.id', 'u.full_name');
+                    if (!user)
+                        continue;
+                    const choices = options[field.key] ?? (options[field.key] = []);
+                    if (!choices.some((option) => option.value === String(user.id)))
+                        choices.push({ value: String(user.id), label: String(user.full_name || `#${user.id}`) });
+                }
+                if (field.type === 'lookup' || field.type === 'belongsTo') {
+                    const choices = options[field.key] ?? [];
+                    if (!choices.some((option) => option.value === String(value))) {
+                        if (field.type === 'lookup')
+                            continue;
+                        try {
+                            // Authorized exactly like opening the related record.
+                            const target = this.registry.get(field.resource);
+                            const current = await this.show(target.name, Number(value), actor);
+                            const title = await this.titler(target);
+                            choices.push({
+                                value: String(current.data.id),
+                                label: title(current.data) ?? `#${current.data.id}`,
+                            });
+                        }
+                        catch (error) {
+                            if (!(error instanceof KitError) || ![403, 404].includes(error.status))
+                                throw error;
+                            continue;
+                        }
+                    }
+                }
+                defaults[field.key] = value;
+            }
         return {
             mode: action,
             name,
             label: resource.label.ar,
+            recordLabel: resource.recordLabel?.ar ?? null,
             fields,
+            /** Initial values of a create form, already checked against the actor's access. */
+            defaults,
             inline,
             options,
             relationSearch,
             orgUnits: units.map((row) => ({ value: String(row.id), label: String(row.name) })),
             scoped: resource.scoped,
+            /** The belongsTo field whose record decides the unit; the form shows no unit picker. */
+            scopeFrom: resource.scope?.from ?? null,
             record: record
                 ? serialize(resource, await this.hydrateOne(this.db, resource, record), ability, actor)
                 : null,
@@ -523,20 +980,84 @@ export class ResourceService {
     async save(name, actor, input, id, transaction) {
         return this.persist(name, actor, input, id, transaction);
     }
-    async persist(name, actor, input, id, transaction, parentWrite) {
+    /**
+     * A write decided by module code rather than by a user's role rules: state transitions,
+     * snapshots and listener updates. It runs the validator, hooks, lookup, relation and
+     * attachment checks, versioning and the audit trail exactly like save(), and skips only
+     * the actor's role rules and organization scope. Values may set any stored field except
+     * sequences and inline children. Updates merge the given values into the stored record.
+     * Returns the full stored record; module code must not send it to users unfiltered.
+     */
+    async systemSave(name, values, id, options) {
+        if (!Number.isSafeInteger(options.actorId) || options.actorId <= 0)
+            throw new KitError(422, 'E_ACTOR', 'systemSave requires the author user id');
+        const actor = { id: options.actorId, orgPaths: [], permissionLevel: 0, rules: [] };
+        return this.persist(name, actor, values, id, options.trx, undefined, {
+            reason: options.reason,
+            version: options.version,
+            chooser: options.chooser,
+        });
+    }
+    /**
+     * Moves the records whose scope follows this parent (`scope: { from }`) to the parent's
+     * current organization unit, through systemSave. Call it from a listener on the parent's
+     * `updated` event, or right after moving the parent. Returns the number of moved records.
+     */
+    async rehome(parentName, parentId, options) {
+        const run = async (trx) => {
+            const parent = await this.findAny(trx, this.registry.get(parentName), parentId);
+            let moved = 0;
+            for (const child of this.registry.all()) {
+                const field = child.scope && child.fields[child.scope.from];
+                if (!field || field.type !== 'belongsTo' || field.resource !== parentName)
+                    continue;
+                const column = field.column ?? columnName(child.scope.from);
+                const ids = await trx(child.name)
+                    .where(column, parentId)
+                    .whereNull('deleted_at')
+                    .whereNot('org_unit_id', Number(parent.orgUnitId))
+                    .orderBy('id')
+                    .pluck('id');
+                for (const id of ids) {
+                    await this.systemSave(child.name, {}, Number(id), { ...options, trx });
+                    moved++;
+                }
+            }
+            return moved;
+        };
+        return options.trx ? run(options.trx) : this.db.transaction(run);
+    }
+    async persist(name, actor, input, id, transaction, parentWrite, system) {
         const resource = this.registry.get(name);
         const action = id === undefined ? 'create' : 'update';
-        const ability = this.authorizeAction(resource, actor, action);
-        const form = writableInput(resource, input);
-        const validated = await resource.validator.validate(form);
+        // System writes carry no role rules; this ability is used only for serialization shape.
+        const ability = system
+            ? buildAbility([{ action: 'manage', subject: 'all' }], this.registry.all())
+            : this.authorizeAction(resource, actor, action);
+        const form = system ? systemInput(resource, input) : writableInput(resource, input);
+        const load = (db, target, key, lock = false) => system
+            ? this.findAny(db, target, key, lock)
+            : this.find(db, target, actor, ability, key, lock);
+        const check = (target, act, record) => {
+            if (!system)
+                this.requireRecord(ability, actor, target, act, record);
+        };
+        const validated = system ? {} : await resource.validator.validate(form);
         const work = async (trx) => {
-            const existing = id === undefined ? {} : await this.find(trx, resource, actor, ability, id, true);
+            const existing = id === undefined ? {} : await load(trx, resource, id, true);
             if (id !== undefined) {
-                this.requireRecord(ability, actor, resource, action, existing);
-                this.requireVersion(resource, existing, input.version);
+                check(resource, action, existing);
+                if (!system || system.version !== undefined)
+                    this.requireVersion(resource, existing, system ? system.version : input.version);
                 if (resource.submittable && existing.docStatus !== 0)
                     throw new KitError(409, 'E_DOCUMENT_LOCKED', 'Only draft documents can be edited');
             }
+            if (system) {
+                // The validator sees the complete form, so a partial update keeps required values.
+                const formKeys = resource.form.filter((key) => resource.fields[key].type !== 'hasMany');
+                const pick = (record) => Object.fromEntries(formKeys.filter((key) => key in record).map((key) => [key, record[key]]));
+                Object.assign(validated, await resource.validator.validate({ ...pick(existing), ...pick(form) }), Object.fromEntries(Object.entries(form).filter(([key]) => !formKeys.includes(key))));
+            }
             const candidate = {
                 ...existing,
                 ...validated,
@@ -546,19 +1067,38 @@ export class ResourceService {
             if (resource.submittable)
                 candidate.docStatus = existing.docStatus ?? 0;
             this.normalizeValues(resource, candidate);
-            if (resource.scoped) {
-                candidate.orgUnitId = input.orgUnitId ?? existing.orgUnitId;
+            const locate = async () => {
+                if (!resource.scoped)
+                    return;
+                if (resource.scope) {
+                    // Inherited scope: the parent decides the unit before any authorization (#45).
+                    const field = resource.fields[resource.scope.from];
+                    const parentId = Number(candidate[resource.scope.from]);
+                    if (field.type !== 'belongsTo' || !Number.isSafeInteger(parentId) || parentId <= 0)
+                        throw new KitError(422, 'E_REQUIRED', `Required field: ${resource.scope.from}`);
+                    const parentResource = this.registry.get(field.resource);
+                    const parent = await load(trx, parentResource, parentId);
+                    check(parentResource, 'view', parent);
+                    candidate.orgUnitId = parent.orgUnitId;
+                }
+                else if (!system || 'orgUnitId' in input || id === undefined)
+                    candidate.orgUnitId = input.orgUnitId ?? existing.orgUnitId;
                 const unit = await trx('org_units')
                     .where('id', Number(candidate.orgUnitId) || -1)
                     .first('path');
+                if (system && !unit)
+                    throw new KitError(422, 'E_ORG_UNIT', 'الوحدة التنظيمية غير موجودة');
                 candidate.orgPath = unit?.path;
-            }
-            this.requireRecord(ability, actor, resource, action, candidate);
+            };
+            await locate();
+            check(resource, action, candidate);
             // 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),
-            ]);
+            const written = new Set(system
+                ? []
+                : [
+                    ...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) ||
@@ -575,6 +1115,16 @@ export class ResourceService {
             const context = { trx, userId: actor.id, action };
             await resource.hooks?.beforeSave?.(candidate, context);
             this.normalizeValues(resource, candidate);
+            // A hook may change the parent of an inherited scope; the unit follows it.
+            if (resource.scope)
+                await locate();
+            // A hook may also move the record: later checks use the unit it chose.
+            if (resource.scoped) {
+                const unit = await trx('org_units')
+                    .where('id', Number(candidate.orgUnitId) || -1)
+                    .first('path');
+                candidate.orgPath = unit?.path;
+            }
             for (const [key, field] of Object.entries(resource.fields)) {
                 if (field.required &&
                     field.type !== 'hasMany' &&
@@ -582,8 +1132,23 @@ export class ResourceService {
                     throw new KitError(422, 'E_REQUIRED', `Required field: ${key}`);
                 if (field.type === 'belongsTo' && candidate[key] !== null && candidate[key] !== undefined) {
                     const related = this.registry.get(field.resource);
-                    const target = await this.find(trx, related, actor, ability, Number(candidate[key]));
-                    this.requireRecord(ability, actor, related, 'view', target);
+                    const target = await load(trx, related, Number(candidate[key]));
+                    check(related, 'view', target);
+                }
+                // A new user, or a record moved by a user to another unit, needs an eligible user.
+                // An unchanged value never blocks other edits, even after the account is disabled.
+                if (field.type === 'user' &&
+                    candidate[key] !== null &&
+                    candidate[key] !== undefined &&
+                    (Number(candidate[key]) !== Number(existing[key]) ||
+                        (!system &&
+                            resource.scoped &&
+                            Number(candidate.orgUnitId) !== Number(existing.orgUnitId)))) {
+                    const eligible = await this.eligibleUsers(trx, resource.scoped ? String(candidate.orgPath ?? '') || null : null, system ? (system.chooser ?? null) : actor)
+                        .where('u.id', Number(candidate[key]))
+                        .first('u.id');
+                    if (!eligible || (resource.scoped && !candidate.orgPath))
+                        throw new KitError(422, 'E_USER_FIELD', `${key}: اختر مستخدماً نشطاً من الوحدة التنظيمية للسجل أو الوحدات الأعلى منها`);
                 }
                 if (field.type === 'lookup' && candidate[key] !== null && candidate[key] !== undefined) {
                     if (!(await trx('lookups')
@@ -605,15 +1170,9 @@ export class ResourceService {
                         scoped: resource.scoped,
                     });
             }
-            if (resource.scoped) {
-                const unit = await trx('org_units')
-                    .where('id', Number(candidate.orgUnitId) || -1)
-                    .first('path');
-                candidate.orgPath = unit?.path;
-            }
             // Hooks may calculate fields, but may never move a record past authorization.
-            this.requireRecord(ability, actor, resource, action, candidate);
-            await this.requireInlineParents(trx, resource, actor, candidate, existing, parentWrite);
+            check(resource, action, candidate);
+            await this.requireInlineParents(trx, resource, actor, candidate, existing, parentWrite, Boolean(system));
             if (id !== undefined &&
                 resource.scoped &&
                 Number(candidate.orgUnitId) !== Number(existing.orgUnitId)) {
@@ -696,12 +1255,26 @@ export class ResourceService {
                     await this.persist(field.resource, actor, {
                         ...data,
                         [field.foreignKey]: row.id,
-                        ...(childResource.scoped ? { orgUnitId: candidate.orgUnitId } : {}),
+                        ...(childResource.scoped && !childResource.scope
+                            ? { orgUnitId: candidate.orgUnitId }
+                            : {}),
                     }, childId === undefined ? undefined : Number(childId), trx, { name, id: Number(row.id), action });
                 }
             }
-            await this.audit(trx, resource, actor, action, saved, Object.keys(form));
+            const changes = [];
+            if (id !== undefined)
+                for (const key of Object.keys(resource.fields)) {
+                    if (resource.fields[key].type === 'hasMany' || !(key in saved))
+                        continue;
+                    const before = existing[key] ?? null;
+                    const after = saved[key] ?? null;
+                    if (JSON.stringify(before) !== JSON.stringify(after))
+                        changes.push({ field: key, before, after });
+                }
+            await this.audit(trx, resource, actor, action, saved, Object.keys(form), changes, system);
             await resource.hooks?.afterSave?.(saved, context);
+            if (system)
+                return (await this.hydrateOne(trx, resource, saved));
             return serialize(resource, await this.hydrateOne(trx, resource, saved), ability, actor);
         };
         return transaction ? work(transaction) : this.db.transaction(work);
@@ -711,7 +1284,7 @@ export class ResourceService {
             throw new KitError(409, 'E_VERSION_CONFLICT', 'تم تعديل السجل بواسطة مستخدم آخر. حدّث الصفحة وحاول مجدداً.');
     }
     /** Inline children share the parent's draft state, organization and update authority. */
-    async requireInlineParents(trx, resource, actor, candidate, existing = {}, parentWrite) {
+    async requireInlineParents(trx, resource, actor, candidate, existing = {}, parentWrite, system = false) {
         for (const parent of this.registry.all()) {
             for (const [key, field] of Object.entries(parent.fields)) {
                 if (field.type !== 'hasMany' || !field.inline || field.resource !== resource.name)
@@ -725,13 +1298,18 @@ export class ResourceService {
                 const action = parentWrite?.name === parent.name && parentWrite.id === Number(parentId)
                     ? parentWrite.action
                     : 'update';
-                const ability = this.authorizeAction(parent, actor, action);
-                const record = await this.find(trx, parent, actor, ability, Number(parentId), true);
-                this.requireRecord(ability, actor, parent, action, record);
-                if (!ability.can(action, subject(parent.name, record), key) ||
-                    actor.permissionLevel <
-                        Math.max(field.permissionLevel ?? 0, parent.hidden?.includes(key) ? 1 : 0))
-                    throw new KitError(403, 'E_FIELD_FORBIDDEN', 'ليس لديك صلاحية تعديل البنود');
+                let record;
+                if (system)
+                    record = await this.findAny(trx, parent, Number(parentId), true);
+                else {
+                    const ability = this.authorizeAction(parent, actor, action);
+                    record = await this.find(trx, parent, actor, ability, Number(parentId), true);
+                    this.requireRecord(ability, actor, parent, action, record);
+                    if (!ability.can(action, subject(parent.name, record), key) ||
+                        actor.permissionLevel <
+                            Math.max(field.permissionLevel ?? 0, parent.hidden?.includes(key) ? 1 : 0))
+                        throw new KitError(403, 'E_FIELD_FORBIDDEN', 'ليس لديك صلاحية تعديل البنود');
+                }
                 if (parent.submittable && record.docStatus !== 0)
                     throw new KitError(409, 'E_DOCUMENT_LOCKED', 'Only draft document lines can be edited');
                 if (parent.scoped &&
@@ -769,8 +1347,94 @@ export class ResourceService {
         };
         return transaction ? work(transaction) : this.db.transaction(work);
     }
-    async audit(trx, resource, actor, action, record, fields) {
+    /**
+     * Amend-by-copy: a cancelled document is copied into a new draft that points to
+     * it through amended_from_id, together with its inline lines. The original stays
+     * cancelled and unchanged; sequence fields receive new numbers.
+     */
+    async amend(name, id, actor, transaction) {
+        const resource = this.registry.get(name);
+        if (!resource.submittable)
+            throw new KitError(409, 'E_DOCUMENT_STATE', 'Only submittable documents can be amended');
+        const ability = this.authorizeAction(resource, actor, 'amend');
+        const work = async (trx) => {
+            const source = await this.find(trx, resource, actor, ability, id, true);
+            this.requireRecord(ability, actor, resource, 'amend', source);
+            if (source.docStatus !== 2)
+                throw new KitError(409, 'E_DOCUMENT_STATE', 'Only cancelled documents can be amended');
+            const existing = await trx(name)
+                .where('amended_from_id', id)
+                .whereNull('deleted_at')
+                .first('id');
+            if (existing)
+                throw new KitError(409, 'E_ALREADY_AMENDED', 'تم تعديل هذا المستند بالنسخ من قبل');
+            const values = {
+                created_by: actor.id,
+                updated_by: actor.id,
+                doc_status: 0,
+                amended_from_id: id,
+            };
+            if (resource.scoped)
+                values.org_unit_id = source.orgUnitId;
+            if (resource.version)
+                values.version = 1;
+            const copied = [];
+            for (const [key, field] of Object.entries(resource.fields)) {
+                if (field.type === 'hasMany' || !(key in source))
+                    continue;
+                const column = field.column ?? columnName(key);
+                if (field.sequence)
+                    values[column] = await sequence(trx, field.sequence);
+                else if (field.type === 'attachment')
+                    continue;
+                else {
+                    values[column] = field.type === 'json' ? JSON.stringify(source[key]) : source[key];
+                    copied.push(key);
+                }
+            }
+            const [row] = await trx(name).insert(values).returning('*');
+            const saved = { ...fromRow(row, resource), orgPath: source.orgPath };
+            for (const field of Object.values(resource.fields)) {
+                if (field.type !== 'hasMany' || !field.inline)
+                    continue;
+                const child = this.registry.get(field.resource);
+                const foreign = child.fields[field.foreignKey].column ?? columnName(field.foreignKey);
+                const lines = await trx(child.name).where(foreign, id).whereNull('deleted_at').orderBy('id');
+                for (const line of lines) {
+                    const copy = {
+                        created_by: actor.id,
+                        updated_by: actor.id,
+                        [foreign]: row.id,
+                    };
+                    if (child.scoped)
+                        copy.org_unit_id = line.org_unit_id;
+                    if (child.version)
+                        copy.version = 1;
+                    for (const [key, childField] of Object.entries(child.fields)) {
+                        const column = childField.column ?? columnName(key);
+                        if (key === field.foreignKey ||
+                            childField.type === 'hasMany' ||
+                            childField.type === 'attachment' ||
+                            !(column in line))
+                            continue;
+                        copy[column] = childField.sequence
+                            ? await sequence(trx, childField.sequence)
+                            : childField.type === 'json'
+                                ? JSON.stringify(line[column])
+                                : line[column];
+                    }
+                    const [inserted] = await trx(child.name).insert(copy).returning('id');
+                    await this.audit(trx, child, actor, 'create', { id: inserted.id }, Object.keys(child.fields));
+                }
+            }
+            await this.audit(trx, resource, actor, 'amend', saved, copied);
+            return serialize(resource, await this.hydrateOne(trx, resource, saved), ability, actor);
+        };
+        return transaction ? work(transaction) : this.db.transaction(work);
+    }
+    async audit(trx, resource, actor, action, record, fields, changes, system) {
         await recordMutation(trx, {
+            ...(system ? { system: true, reason: system.reason } : {}),
             module: this.registry.owner(resource.name),
             resource: resource.name,
             id: record.id,
@@ -778,6 +1442,7 @@ export class ResourceService {
             impersonatorId: actor.impersonatorId,
             action,
             fields,
+            changes,
         });
     }
 }