@adula/kit 1.0.0 → 1.2.0

package/build/agent/AGENTS.template.md

@@ -16,11 +16,11 @@ Structure
 8. Deletes are soft. Changeable lists come from lookups. Approvable documents use `submittable: true`.
 9. Notify via notify(), number via sequence, configure via settings. Nothing else.
 
-Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). 11. Never write crypto, sessions, or auth flows; use kit. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
+Security 10. Every route passes the authorize middleware. Every transformer uses `serialize` (explicit pick). `systemSave` and `rehome` skip role rules: use them only in listeners and module services after an explicit authorization, never in a controller or route (enforced by lint). 11. Never write crypto, sessions, or auth flows; use kit. 2FA and impersonation changes need a human review. 12. Never delete or weaken a test to make the build pass.
 
 UI 13. Before designing or changing any interface, read and apply `.agents/skills/adula-frontend-design/SKILL.md` (the kit's bundled frontend-design skill for business applications). At project kickoff, request the company's identity before the first design: name, logo, colors, fonts and brand guidelines when available. Reuse supplied identity, ask only for missing information, and preserve it in project-owned docs/design-identity.md. Fill the resource definition before writing a page. Override only via pages/<resource>/. 14. Compose interfaces from the project-owned shadcn/ui components in inertia/components/ui/. Use Button, Input, Select, Table, Card and the other registry primitives instead of hand-styled native controls or homemade equivalents. Semantic HTML for structure, text and form submission is allowed. Add components only via `node ace adula:ui add`, never `shadcn add`. 15. All forms (including create/edit) and row/record detail views use shadcn Dialog (modal) by default. Use ResourceSurface for resource forms/details; do not choose a standalone page, Sheet or custom overlay unless the user explicitly requests that alternative. View dialogs close on outside click; edit dialogs ask before closing by default. Honor system preferences for Gregorian, Hijri or both calendars and reduced motion. RTL by default; Arabic labels; English identifiers. Installation terminal instructions are English. Preserve explicit user exceptions and project-owned customizations.
 
-Boundaries 16. Never modify node_modules/@adula and never use patch-package (enforced by lint). Do not re-implement a kit service under another name (checked in review). 17. A limitation is recorded in KIT_GAPS.md (template inside) and reported to the developer — never worked around. 18. Only packages already in package.json. Ask before adding one. 19. New module or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
+Boundaries 16. Never modify node_modules/@adula and never use patch-package (enforced by lint). Do not re-implement a kit service under another name (checked in review). 17. A limitation is recorded in KIT_GAPS.md (template inside) and reported to the developer — never worked around. Describe the kit capability, not this project, and reproduce it on a new application from create-app. The developer submits it through the prefilled form link printed by `node ace adula:gaps report`, then records `Issue: #<number>`; never open kit issues through the API. 18. Only packages already in package.json. Ask before adding one. 19. New module or workflow → run the idea-review skill first. Field changes do not need it. 20. Before finishing: `npm run typecheck && npm test && node ace adula:doctor`.
 <!-- adula-kit:end -->
 
 ## Project rules

package/build/agent/capabilities.md

@@ -1,4 +1,4 @@
-# adula-kit capabilities (1.0.0)
+# adula-kit capabilities (1.2.0)
 
 Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by the kit.
 
@@ -16,16 +16,17 @@ Generated by `node ace adula:capabilities`. Read this before proposing a module;
 | json | jsonb |
 | attachment | attachments row id; per-field accept/maxSize |
 | belongsTo | foreign key, preloaded, restrict on delete |
+| user | users foreign key, restrict on delete; choices are active members of the record unit or its ancestors; related as { id, fullName } |
 | hasMany | child resource; inline rows saved with the parent |
 | lookup | lookups group key |
 
 Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column.
 
-Resource options: scoped (required), submittable (docStatus, submit/cancel/amend-by-copy), version (optimistic locking, default with submittable), customFields, list / form / show / serialize / hidden, actions, hooks.beforeSave / hooks.afterSave.
+Resource options: scoped (required), scope.from (the unit follows a required belongsTo parent), title (fields that name the record in relations, pickers, tasks and approvals), submittable (docStatus, submit/cancel/amend-by-copy), version (optimistic locking, default with submittable), customFields, list / form / show / serialize / hidden, actions, hooks.beforeSave / hooks.afterSave.
 
-Role rule conditions: $eq, $ne, $in, $lt, $gt, $like on scalar fields; unsupported conditions are refused. Organization scope is always added with AND.
+Role rule conditions: $eq, $ne, $in, $lt, $gt, $like on scalar fields; unsupported conditions are refused. Organization scope is always added with AND. `$actor.id` names the signed-in user on user fields, createdBy and updatedBy ($eq, $ne, $in), bound per request.
 
-Workflow steps: condition, update, notify, approval, delay, http, end.
+Workflow steps: condition, update, notify, approval, decision, delay, http, end. Workflow and step names: use lower-case letters, digits and underscores, starting with a letter (for example release_approval, notify_approved).
 
 ## Services
 
@@ -33,18 +34,22 @@ Workflow steps: condition, update, notify, approval, delay, http, end.
 - **Records and collaboration:** `RecordCollaboration`, `followerListeners`, `Assignments`, `SavedViews`, `logActivity`
 - **Documents and workflows:** `defineWorkflow`, `WorkflowEngine`, `workflowListeners`
 - **Notifications and messages:** `notify`, `notifyWithTemplate`, `MessageTemplates`, `deliverNotificationMail`, `listenForNotifications`, `NotificationsAdmin`
-- **Integration:** `Webhooks`, `signWebhook`, `openApiDocument`, `ImportBatches`, `renderPrintHtml`, `htmlToPdf`
+- **Integration:** `Webhooks`, `signWebhook`, `InboundWebhooks`, `openApiDocument`, `ImportBatches`, `renderPrintHtml`, `htmlToPdf`
 - **Security:** `UserInvitations`, `UsersAdmin`, `RolesAdmin`
 - **Data and operations:** `sequence`, `Settings`, `SettingsAdmin`, `publishOutbox`, `consumeEvent`, `recordMutation`, `moveOrgUnit`, `migrateStorage`, `verifyBackup`, `runtimeHealth`
 
 ## Extension points
 
 - Resource hooks (beforeSave, afterSave) inside the save transaction
+- ResourceService.systemSave for module-decided writes (validator, hooks and audit, no role rules); ResourceService.rehome after a parent moves
+- Assignment closing notes (Assignments closeNote: optional or required); managed assignments (managed: true) closed by module code with Assignments.close
 - Page override: inertia/pages/<resource>/{index,form,show}.tsx replaces the generated page
+- Create links with defaults: /resources/<resource>/create?defaults[field]=value
 - Domain events <module>.<resource>.{created,updated,deleted,submitted,cancelled,amended} with idempotent listeners
 - Module workflows (Module.workflows) with versioned definitions
 - Message templates edited per deployment
 - Outgoing webhooks and the bearer-token /api/v1 API
+- Signed inbound webhooks raising inbound.<source>.<event> through the outbox
 
 ## Outside the kit
 

package/build/agent/skills/adula-frontend-design/SKILL.md

@@ -46,7 +46,7 @@ Install missing registry components with `node ace adula:ui add <component>`. Ne
 
 Every form and every row/record detail view opens in a shadcn Dialog unless the user explicitly requests another presentation. This includes create/edit forms and custom page overrides. Do not infer a page or Sheet exception from screen size, form length or personal design preference.
 
-For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
+For resource routes, use `ResourcePage`, which selects the modal surface by default. For a custom form/detail override, wrap its content in `ResourceSurface` with a title, description and the list's `backHref`. It keeps direct URLs usable and returns to the list when dismissed. From a list, open records with `openRecord(resource, id, 'show' | 'edit')` (exported by `resource-surface`): the dialog opens over the mounted list, and closing keeps its query, loaded rows and scroll. Use `presentation="page"` only for a user-requested page exception. Keep embedded line-item fields within their parent's form, not separate nested forms. Search and filter controls may stay in the list toolbar; their form element is submission structure, not a separate record form.
 
 Give every Dialog a visible DialogTitle and a useful DialogDescription. Keep long content scrollable within the viewport, Arabic RTL alignment, an accessible close control, focus containment and Escape dismissal. Use shadcn components inside the modal too. Keep validation and conflict messages inside it, preserve typed values on errors, and keep unauthorized actions absent. Do not replace server authorization with UI checks.
 

package/build/commands/doctor.js

@@ -1,9 +1,11 @@
 import { BaseCommand } from '@adonisjs/core/ace';
 import { fileURLToPath } from 'node:url';
-import { diagnose } from '../src/commands/doctor.js';
+import { diagnose, diagnoseResourceSnapshots, diagnoseOutbox, diagnoseWorkflowRoles, } from '../src/commands/doctor.js';
+import { runtimeHealth } from '../src/core/health.js';
 import { diagnoseAttachments } from '../src/attachments/doctor.js';
 import { Settings } from '../src/services/settings.js';
 import { MigrationRunner } from '@adonisjs/lucid/migration';
+import { readFile } from 'node:fs/promises';
 export default class Doctor extends BaseCommand {
     static commandName = 'adula:doctor';
     static description = 'Check kit ownership, installation and backup readiness';
@@ -12,6 +14,7 @@ export default class Doctor extends BaseCommand {
         const { default: db } = await import('@adonisjs/lucid/services/db');
         const findings = await diagnose(fileURLToPath(this.app.appRoot), new Settings(db.connection().getWriteClient()), this.app.inProduction, process.env);
         findings.push(await diagnoseAttachments(db.connection().getWriteClient()));
+        findings.push(diagnoseOutbox(await runtimeHealth(db.connection().getWriteClient())));
         const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
         const missing = migrations.filter((entry) => entry.status === 'corrupt');
         const pending = migrations.filter((entry) => entry.status === 'pending');
@@ -24,6 +27,39 @@ export default class Doctor extends BaseCommand {
                     ? `${pending.length} pending migrations; run migration:run after the deployment backup`
                     : 'Migration files and database history agree',
         });
+        const sources = [];
+        for (const entry of pending)
+            for (const extension of ['.ts', '.js'])
+                try {
+                    const file = `${entry.name}${extension}`;
+                    sources.push({ file, source: await readFile(this.app.makePath(file), 'utf8') });
+                    break;
+                }
+                catch { }
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch { }
+        if (registry) {
+            // Before the 1.1 migrations run, roles have no key column yet (an unfinished upgrade).
+            const keyed = await db.connection().getWriteClient().schema.hasColumn('roles', 'key');
+            const roles = await db.from('roles').select(keyed ? ['key', 'name'] : ['name']);
+            findings.push(diagnoseWorkflowRoles(registry.workflows(), roles.map((role) => ({
+                key: role.key ? String(role.key) : null,
+                name: String(role.name),
+            }))));
+        }
+        if (registry)
+            findings.push(diagnoseResourceSnapshots(sources, (name) => {
+                try {
+                    return registry.get(name);
+                }
+                catch {
+                    return undefined;
+                }
+            }));
         for (const finding of findings)
             this.logger.log(`${finding.status.toUpperCase()} ${finding.check}: ${finding.message}`);
         if (findings.some((finding) => finding.status === 'fail'))

package/build/commands/gaps.js

@@ -10,7 +10,7 @@ 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';
-    static description = 'Show the project gap report with private names masked before it is sent';
+    static description = 'Show the project gap report with private names masked, and links that open the kit gap form prefilled';
     static options = { startApp: false };
     async run() {
         if (this.action !== 'report')
@@ -23,16 +23,26 @@ export default class Gaps extends BaseCommand {
         catch {
             throw new Error('KIT_GAPS.md does not exist; adula:install creates it');
         }
-        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}`);
+        const { masked, gaps } = gapReport(content);
+        this.logger.info(`${gaps.length} gap(s) recorded in KIT_GAPS.md`);
+        for (const gap of gaps)
+            this.logger.log(`  ${gap.title}${gap.issue ? ` (reported: ${gap.issue})` : ''}`);
         if (!this.yes) {
-            const confirmed = await this.prompt.confirm('Show the full masked report? Nothing is sent anywhere by this command.');
+            const confirmed = await this.prompt.confirm('Show the full masked report and the issue links? Nothing is sent anywhere by this command.');
             if (!confirmed)
                 return;
         }
         this.logger.log(masked);
+        const pending = gaps.filter((gap) => gap.url);
+        if (!pending.length)
+            return;
+        this.logger.info('Review each link in a browser, submit the form, then write the issue number in the entry as "Issue: #<number>".');
+        for (const gap of pending) {
+            this.logger.log(`\n${gap.title}`);
+            if (gap.missing.length)
+                this.logger.warning(`Complete before submitting: ${gap.missing.join(', ')}`);
+            this.logger.log(gap.url);
+        }
     }
 }
 __decorate([

package/build/commands/install.js

@@ -1,7 +1,9 @@
 import { BaseCommand } from '@adonisjs/core/ace';
 import { readFile, writeFile, access } from 'node:fs/promises';
 import { Settings } from '../src/services/settings.js';
+import { seedModules } from '../src/core/module_seed.js';
 import { syncAgentAssets } from '../src/commands/agent_assets.js';
+import { GAPS_TEMPLATE } from '../src/commands/gap_report.js';
 import { KIT_VERSION } from '../src/version.js';
 import { fileURLToPath } from 'node:url';
 export default class Install extends BaseCommand {
@@ -32,10 +34,12 @@ export default class Install extends BaseCommand {
             let role = await trx('roles').where('name', 'administrator').first();
             if (!role) {
                 const [created] = await trx('roles')
-                    .insert({ name: 'administrator', permission_level: 1 })
+                    .insert({ name: 'administrator', key: 'administrator', permission_level: 1 })
                     .returning('*');
                 role = created;
             }
+            else if (!role.key && !(await trx('roles').where('key', 'administrator').first()))
+                await trx('roles').where('id', role.id).update({ key: 'administrator' });
             // Repair a missing bootstrap grant even when the role already exists.
             // The transaction lock makes repeated/concurrent installation idempotent.
             if (!(await trx('role_rules')
@@ -55,12 +59,22 @@ export default class Install extends BaseCommand {
                 .ignore();
             await new Settings(trx).set('kit.version', KIT_VERSION);
         });
+        // Module lookups and default roles: added when missing, never overwritten.
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch (error) {
+            this.logger.warning(`Module defaults skipped: ${error.message}`);
+        }
+        if (registry) {
+            const seeded = await seedModules(knex, registry, user.id);
+            this.logger.info(`Module defaults: ${seeded.lookups} lookup rows added; roles created: ${seeded.created.join(', ') || 'none'}; adopted by name: ${seeded.adopted.join(', ') || 'none'}`);
+        }
         for (const [name, content] of [
             ['CLAUDE.md', 'Read and follow AGENTS.md.\nThe project rules are maintained there.\n'],
-            [
-                'KIT_GAPS.md',
-                '# Kit gaps\n\nRecord Needed by, Tried, Blocked because, Proposed kit change, Workaround.\n',
-            ],
+            ['KIT_GAPS.md', GAPS_TEMPLATE],
         ]) {
             const path = this.app.makePath(name);
             try {

package/build/commands/main.js

@@ -1,4 +1,5 @@
 import Resource from './resource.js';
+import ResourceSnapshot from './resource_snapshot.js';
 import Doctor from './doctor.js';
 import Install from './install.js';
 import Capabilities from './capabilities.js';
@@ -9,6 +10,7 @@ import StorageMigrate from './storage_migrate.js';
 import Gaps from './gaps.js';
 const commands = [
     Resource,
+    ResourceSnapshot,
     Doctor,
     Install,
     Capabilities,

package/build/commands/module_add.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { BaseCommand, args, flags } from '@adonisjs/core/ace';
 import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
 import { identifier } from '../src/resource/define_resource.js';
-import { appendMarkedItem } from '../src/commands/source_markers.js';
+import { appendMarkedItem, moduleSource } from '../src/commands/source_markers.js';
 export default class ModuleAdd extends BaseCommand {
     static commandName = 'adula:module:add';
     static description = 'Create and register an application-owned module';
@@ -44,7 +44,7 @@ export default class ModuleAdd extends BaseCommand {
             'tests',
         ])
             await mkdir(this.app.makePath('app/modules', this.name, directory), { recursive: true });
-        await writeFile(this.app.makePath('app/modules', this.name, 'module.ts'), `import type { Module } from '@adula/kit'\n// adula:imports\nexport default { name: '${this.name}', label: { ar: '${this.name}', en: '${this.name}' }, reference: ${Boolean(this.reference)}, dependsOn: [], resources: [/* adula:resources */] } satisfies Module\n`, { flag: 'wx' });
+        await writeFile(this.app.makePath('app/modules', this.name, 'module.ts'), moduleSource(this.name, { reference: Boolean(this.reference), typed: true }), { flag: 'wx' });
         await writeFile(indexPath, next);
         this.logger.success(`Created ${this.name}. Fill bilingual labels and declare dependencies before adding resources.`);
     }

package/build/commands/resource.js

@@ -18,7 +18,7 @@ export default class Resource extends BaseCommand {
         }
         const files = await generateResource(fileURLToPath(this.app.appRoot), this.name, this.module);
         files.forEach((file) => this.logger.success(file));
-        this.logger.info('Set bilingual labels, fill the resource definition, migrate, and run the generated security contract.');
+        this.logger.info('Set bilingual labels (label: the plural list heading; recordLabel: the singular record noun) and fill the resource definition. The generated migration embeds the definition as scaffolded: after filling the definition, run `node ace adula:resource:snapshot <name>` to refresh the pending migration, and update the model, factory and contract fixture, before migration:run. adula:doctor reports a pending migration that differs. Then run the generated security contract.');
     }
 }
 __decorate([

package/build/commands/resource_snapshot.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '@adonisjs/core/ace';
+/**
+ * Rewrites the definition embedded in a resource's generated create-migration from the
+ * current resource, while that migration has not run yet (#20). A migration that already
+ * ran is never edited: change the table with a new expand migration instead.
+ */
+export default class ResourceSnapshot extends BaseCommand {
+    static commandName: string;
+    static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    name: string;
+    run(): Promise<void>;
+}

package/build/commands/resource_snapshot.js

@@ -0,0 +1,61 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseCommand, args } from '@adonisjs/core/ace';
+import { readFile, writeFile } from 'node:fs/promises';
+import { MigrationRunner } from '@adonisjs/lucid/migration';
+import { embeddedResource, resourceSnapshot, rewriteResourceSnapshot, } from '../src/commands/snapshot.js';
+/**
+ * Rewrites the definition embedded in a resource's generated create-migration from the
+ * current resource, while that migration has not run yet (#20). A migration that already
+ * ran is never edited: change the table with a new expand migration instead.
+ */
+export default class ResourceSnapshot extends BaseCommand {
+    static commandName = 'adula:resource:snapshot';
+    static description = "Refresh a pending generated create-migration from the resource's current definition";
+    static options = { startApp: true };
+    async run() {
+        const { default: db } = await import('@adonisjs/lucid/services/db');
+        const { registry } = (await this.app.import('#start/modules'));
+        let resource;
+        try {
+            resource = registry.get(this.name);
+        }
+        catch {
+            this.logger.error(`Unknown resource: ${this.name}. Register it in its module first.`);
+            this.exitCode = 1;
+            return;
+        }
+        const migrations = await new MigrationRunner(db, this.app, { direction: 'up' }).getList();
+        const matches = [];
+        for (const entry of migrations)
+            for (const extension of ['.ts', '.js'])
+                try {
+                    const file = `${entry.name}${extension}`;
+                    const source = await readFile(this.app.makePath(file), 'utf8');
+                    if (embeddedResource(source) === this.name)
+                        matches.push({ file, source, pending: entry.status === 'pending' });
+                    break;
+                }
+                catch { }
+        const pending = matches.filter((match) => match.pending);
+        if (!pending.length) {
+            this.logger.error(matches.length
+                ? `${matches[0].file} already ran; never edit it. Add an expand migration for the new columns instead.`
+                : `No generated create-migration embeds ${this.name}.`);
+            this.exitCode = 1;
+            return;
+        }
+        for (const match of pending) {
+            await writeFile(this.app.makePath(match.file), rewriteResourceSnapshot(match.source, resourceSnapshot(resource)));
+            this.logger.success(match.file);
+        }
+        this.logger.info('Update the model, factory and contract fixture to the same fields, then run migration:run.');
+    }
+}
+__decorate([
+    args.string({ description: 'Resource name' })
+], ResourceSnapshot.prototype, "name", void 0);

package/build/database/migrations/1770000000011_kit_managed_assignments.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitManagedAssignments extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000011_kit_managed_assignments.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createManagedAssignmentsSchema } from '../../src/database/schema.js';
+export default class KitManagedAssignments extends BaseSchema {
+    async up() {
+        await createManagedAssignmentsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000012_kit_role_keys.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitRoleKeys extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000012_kit_role_keys.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createRoleKeysSchema } from '../../src/database/schema.js';
+export default class KitRoleKeys extends BaseSchema {
+    async up() {
+        await createRoleKeysSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000013_kit_notification_targets.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitNotificationTargets extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000013_kit_notification_targets.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createNotificationTargetsSchema } from '../../src/database/schema.js';
+export default class KitNotificationTargets extends BaseSchema {
+    async up() {
+        await createNotificationTargetsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000014_kit_upload_grants.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitUploadGrants extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000014_kit_upload_grants.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createUploadGrantsSchema } from '../../src/database/schema.js';
+export default class KitUploadGrants extends BaseSchema {
+    async up() {
+        await createUploadGrantsSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/database/migrations/1770000000015_kit_inbound_webhooks.d.ts

@@ -0,0 +1,5 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+export default class KitInboundWebhooks extends BaseSchema {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}

package/build/database/migrations/1770000000015_kit_inbound_webhooks.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createInboundWebhooksSchema } from '../../src/database/schema.js';
+export default class KitInboundWebhooks extends BaseSchema {
+    async up() {
+        await createInboundWebhooksSchema(this.db.getWriteClient());
+    }
+    async down() {
+        throw new Error('Kit migrations are additive. Restore a tested backup instead of rolling back.');
+    }
+}

package/build/index.d.ts

@@ -11,34 +11,41 @@ export { packedResourceRules } from './src/auth/packed_rules.js';
 export type { Actor, Rule, KitAbility } from './src/auth/ability.js';
 export { ActorStore } from './src/auth/actor_store.js';
 export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js';
-export { ResourceService } from './src/admin/resource_service.js';
+export { ACTOR_ID, resolveActorConditions } from './src/auth/conditions.js';
+export { ResourceService, canQueryField } from './src/admin/resource_service.js';
+export type { AggregateOptions, AggregateRow, ListOptions } 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, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, createManagedAssignmentsSchema, createRoleKeysSchema, createNotificationTargetsSchema, createUploadGrantsSchema, createInboundWebhooksSchema, } from './src/database/schema.js';
 export { defineWorkflow, nextStep } from './src/workflows/define_workflow.js';
-export type { WorkflowDefinition, WorkflowInput, WorkflowStep, WorkflowEvent, StepContext, Recipients, } from './src/workflows/define_workflow.js';
+export type { WorkflowDefinition, WorkflowInput, WorkflowStep, WorkflowEvent, StepContext, Recipients, DecisionOutcome, } from './src/workflows/define_workflow.js';
 export { WorkflowEngine, workflowListeners } from './src/workflows/engine.js';
-export type { WorkflowRun, WorkflowRunStatus, WorkflowOptions } from './src/workflows/engine.js';
+export type { WorkflowRun, WorkflowRunStatus, WorkflowOptions, WorkflowDecisionForm, } from './src/workflows/engine.js';
 export { ImportBatches, importCell, IMPORT_ROW_LIMIT } from './src/integrations/imports.js';
 export type { ImportBatch, ImportStatus, ImportTarget, ActorSource, } from './src/integrations/imports.js';
 export { openApiDocument } from './src/integrations/openapi.js';
 export { renderPrintHtml, htmlToPdf } from './src/integrations/print.js';
 export type { PrintIdentity, PrintInput } from './src/integrations/print.js';
 export { Webhooks, signWebhook, WEBHOOK_MAX_ATTEMPTS } from './src/integrations/webhooks.js';
+export { InboundWebhooks, inboundEventName, INBOUND_BODY_LIMIT, INBOUND_RETENTION_DAYS, } from './src/integrations/inbound_webhooks.js';
+export type { InboundSource, InboundSourceInput, InboundDelivery, InboundReceipt, } from './src/integrations/inbound_webhooks.js';
 export type { SecretBox, Webhook, WebhookDelivery, WebhookOptions, HttpPoster, } from './src/integrations/webhooks.js';
 export { MessageTemplates, DEFAULT_TEMPLATES, renderTemplate, notifyWithTemplate, deliverNotificationMail, listenForNotifications, } from './src/core/message_templates.js';
 export type { TemplateDefinition, MessageTemplate, RenderedMessage, MailSender, NotificationSignal, } from './src/core/message_templates.js';
 export { Assignments } from './src/collaboration/assignments.js';
-export type { Assignment, AssignmentPage, AssignmentStatus, } from './src/collaboration/assignments.js';
+export type { Assignment, AssignmentPage, AssignmentOptions, CloseNotePolicy, AssignmentStatus, } from './src/collaboration/assignments.js';
 export { RecordCollaboration, followerListeners } from './src/collaboration/record_collaboration.js';
 export type { ActorLoader, CommentEntry, FieldChangeEntry, RecordCollaborationState, MentionCandidate, } from './src/collaboration/record_collaboration.js';
 export type { FieldChange } from './src/events/record_mutation.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 { grantUpload, redeemUploadGrant, pruneUploadGrants, UPLOAD_GRANT_MAX_TTL_MS, } from './src/attachments/upload_grants.js';
+export type { UploadGrantInput, UploadGrant, RedeemedUploadGrant, } from './src/attachments/upload_grants.js';
 export { migrateStorage } from './src/attachments/storage_migrate.js';
 export type { StorageDisk, StorageMigrationOptions, StorageMigrationResult, } from './src/attachments/storage_migrate.js';
 export { diagnoseAttachments } from './src/attachments/doctor.js';
 export { Settings, sequence, notify } from './src/services/settings.js';
+export type { NotificationTarget } from './src/services/settings.js';
 export { uiPreferences, validateUiPreferences, UI_PREFERENCES_KEY, DEFAULT_UI_PREFERENCES, } from './src/core/ui_preferences.js';
 export type { UiPreferences, CalendarSystem, CalendarPreference, } from './src/core/ui_preferences.js';
 export { moveOrgUnit } from './src/org/org_service.js';
@@ -51,6 +58,8 @@ export type { BackupObject, BackupStatus } from './src/services/backup.js';
 export { ActivityAdmin, logActivity } from './src/core/activity.js';
 export type { ActivityEntry, ActivityFilters, ActivityPage, ActivityRow, } from './src/core/activity.js';
 export { RolesAdmin, ALL_SUBJECT_LABEL } from './src/core/roles.js';
+export { seedModules } from './src/core/module_seed.js';
+export type { ModuleSeedResult } from './src/core/module_seed.js';
 export type { RoleSummary, RoleDetail, RoleRule, RuleInput, RoleMatrix, MatrixSubject, MatrixField, } from './src/core/roles.js';
 export { UsersAdmin } from './src/core/users.js';
 export { UserInvitations, type InvitationDelivery } from './src/core/user_invitations.js';

package/build/index.js

@@ -7,20 +7,23 @@ export { buildAbility, canRecord, inOrgScope } from './src/auth/ability.js';
 export { packedResourceRules } from './src/auth/packed_rules.js';
 export { ActorStore } from './src/auth/actor_store.js';
 export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js';
-export { ResourceService } from './src/admin/resource_service.js';
+export { ACTOR_ID, resolveActorConditions } from './src/auth/conditions.js';
+export { ResourceService, canQueryField } 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, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, createManagedAssignmentsSchema, createRoleKeysSchema, createNotificationTargetsSchema, createUploadGrantsSchema, createInboundWebhooksSchema, } from './src/database/schema.js';
 export { defineWorkflow, nextStep } from './src/workflows/define_workflow.js';
 export { WorkflowEngine, workflowListeners } from './src/workflows/engine.js';
 export { ImportBatches, importCell, IMPORT_ROW_LIMIT } from './src/integrations/imports.js';
 export { openApiDocument } from './src/integrations/openapi.js';
 export { renderPrintHtml, htmlToPdf } from './src/integrations/print.js';
 export { Webhooks, signWebhook, WEBHOOK_MAX_ATTEMPTS } from './src/integrations/webhooks.js';
+export { InboundWebhooks, inboundEventName, INBOUND_BODY_LIMIT, INBOUND_RETENTION_DAYS, } from './src/integrations/inbound_webhooks.js';
 export { MessageTemplates, DEFAULT_TEMPLATES, renderTemplate, notifyWithTemplate, deliverNotificationMail, listenForNotifications, } from './src/core/message_templates.js';
 export { Assignments } from './src/collaboration/assignments.js';
 export { RecordCollaboration, followerListeners } from './src/collaboration/record_collaboration.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 { grantUpload, redeemUploadGrant, pruneUploadGrants, UPLOAD_GRANT_MAX_TTL_MS, } from './src/attachments/upload_grants.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';
@@ -32,6 +35,7 @@ export { recordMutation } from './src/events/record_mutation.js';
 export { assessBackup, verifyBackup } from './src/services/backup.js';
 export { ActivityAdmin, logActivity } from './src/core/activity.js';
 export { RolesAdmin, ALL_SUBJECT_LABEL } from './src/core/roles.js';
+export { seedModules } from './src/core/module_seed.js';
 export { UsersAdmin } from './src/core/users.js';
 export { UserInvitations } from './src/core/user_invitations.js';
 export { OrgUnitsAdmin } from './src/core/org_units.js';

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

@@ -10,3 +10,10 @@ export declare function serialize(resource: Resource, record: RecordData, abilit
 export declare function writableInput(resource: Resource, input: RecordData): {
     [k: string]: unknown;
 };
+/**
+ * Values module code may write through ResourceService.systemSave: every stored field
+ * except sequences and inline children, plus the organization unit when it is not inherited.
+ */
+export declare function systemInput(resource: Resource, input: RecordData): {
+    [k: string]: unknown;
+};

package/build/src/admin/contracts.js

@@ -13,7 +13,7 @@ export function selectedFields(resource, ability, options = {}) {
             ...(options.write
                 ? Object.keys(resource.fields)
                 : (resource.serialize ?? [...resource.list, ...resource.show])),
-            ...Object.keys(resource.fields).filter((k) => resource.fields[k].type === 'belongsTo'),
+            ...Object.keys(resource.fields).filter((k) => ['belongsTo', 'user'].includes(resource.fields[k].type)),
             ...(options.extra ?? []),
             ...conditionFields(ability, resource),
         ]),
@@ -92,7 +92,7 @@ export function serialize(resource, record, ability, actor) {
 export function writableInput(resource, input) {
     const allowed = new Set([
         ...resource.form,
-        ...(resource.scoped ? ['orgUnitId'] : []),
+        ...(resource.scoped && !resource.scope ? ['orgUnitId'] : []),
         ...(resource.version ? ['version'] : []),
     ]);
     for (const key of Object.keys(input))
@@ -100,3 +100,16 @@ export function writableInput(resource, input) {
             throw new KitError(422, 'E_FIELD_NOT_WRITABLE', `Field is not writable: ${key}`);
     return Object.fromEntries(Object.entries(input).filter(([key]) => resource.form.includes(key)));
 }
+/**
+ * Values module code may write through ResourceService.systemSave: every stored field
+ * except sequences and inline children, plus the organization unit when it is not inherited.
+ */
+export function systemInput(resource, input) {
+    for (const key of Object.keys(input)) {
+        const field = resource.fields[key];
+        const unit = key === 'orgUnitId' && resource.scoped && !resource.scope;
+        if (!unit && (!field || field.type === 'hasMany' || field.sequence))
+            throw new KitError(422, 'E_FIELD_NOT_WRITABLE', `Field is not writable: ${key}`);
+    }
+    return Object.fromEntries(Object.entries(input).filter(([key]) => key in resource.fields));
+}

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

@@ -26,6 +26,7 @@ export interface ResourceController {
     create(ctx: HttpContext): Promise<unknown>;
     edit(ctx: HttpContext): Promise<unknown>;
     options(ctx: HttpContext): Promise<unknown>;
+    aggregate(ctx: HttpContext): Promise<unknown>;
 }
 /** The host supplies its authenticated actor; ResourceService authorizes every action. */
 export declare function createResourceController(resolveRuntime: (ctx: HttpContext) => Promise<ResourceRuntime>, renderList?: (ctx: HttpContext, resource: Resource, result: ResourceList) => unknown, renderForm?: (ctx: HttpContext, resource: Resource, editor: ResourceEditor) => unknown, renderShow?: (ctx: HttpContext, resource: Resource, result: ResourceShow) => unknown): new () => ResourceController;