@adula/kit 0.2.0-alpha.4 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @adula/kit
 
-Experimental 0.2.0-alpha.4 resource framework for AdonisJS 7 and PostgreSQL 17. Node 24 or later is required. MIT licensed. The target is the complete approved 1.0 scope; it has not passed acceptance.
+Resource framework for AdonisJS 7 and PostgreSQL 17, version 1.0.0 (accepted by the owner, ADR 028). Node 24 or later is required. MIT licensed. The public API in `api/kit-api.json` follows semantic versioning.
 
 ## Install into a consumer
 
@@ -28,4 +28,14 @@ Doctor measures the deployment's `storage/uploads` directory and warns above 5 d
 
 ## Current limitations
 
-Attachment ownership, upload/download, storage migration, authentication lifecycle/rate limiting, generic resource UI and core administration have local integration consumers and tests. Real OAuth/SMTP, full Tuyau field contracts, human/performance acceptance, XState workflows, later business features, staging/offsite restoration and a genuine minor-version consumer upgrade remain open. Submission envelopes are durable records in pending_definition state, not running workflows. See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md). Version 0.2.0-alpha.4 targets alpha; the owner-authorized latest alias remains on 0.2.0-alpha.1.
+Phases 3 and 4 (collaboration, assignments, templates and realtime notifications,
+CSV import, printing, webhooks, API tokens/OpenAPI, amend-by-copy and versioned
+XState workflows) are implemented with PostgreSQL tests; see the
+[business features guide](https://github.com/adulash/adula-kit/blob/main/docs/business-features.md).
+
+- Two-factor authentication is not included; it is planned for 2.0 (ADR 027).
+- Impersonation was reviewed by automated adversarial and black-box tests only; its
+  human security review is deferred to 2.0 (ADR 027).
+- XLSX import is not available (GAP-006); CSV is.
+
+See [implementation status](https://github.com/adulash/adula-kit/blob/main/docs/implementation-status.md), [gaps](https://github.com/adulash/adula-kit/blob/main/KIT_GAPS.md) and [1.0 acceptance](https://github.com/adulash/adula-kit/blob/main/docs/acceptance-1.0.md).

package/build/agent/capabilities.md

@@ -1,13 +1,55 @@
-# Current capabilities
+# adula-kit capabilities (1.0.0)
 
-Version 0.2.0-alpha.4, experimental alpha. Resource definitions and registry; six flat condition operators (typed limits documented in KIT_GAPS.md); CASL evaluation with structural ltree scope; JSON/Inertia resource CRUD; field contracts; keyset pagination; sequences/lookups/settings; soft deletion; optimistic concurrency; atomic inline writes/activity/outbox; deduplicated database listeners; org moves; attachment ownership/storage migration; saved views (queries limited to fields the author may query); attachment fields with per-field `accept`/`maxSize` limits and daily pruning of unbound uploads; case-insensitive e-mail identity with ownership proof before OAuth linking; `adula:gaps report`; core administration services; resource/module commands; copied shadcn UI and installation diagnostics.
+Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by the kit.
 
-The reference consumer wires authentication/session lifecycle, admin screens, authorized attachments, optional MCP, Redis actor caching, a queue worker, one scheduler and backup/restore drills. Educational modules are isolated test fixtures, not installed application features. The agent ships business frontend-design and idea-review skills, company identity intake and modal defaults. Real SMTP receipt/recovery and isolated offsite local/source-S3 attachment recovery are documented in the source repository's confirmed-achievements ledger. OAuth is optional and externally unverified. Source-S3 recovery is integrated into the operational backup commands and verified directly; local Docker backup/recovery also passed; natural scheduled operation and staging remain pending; each consumer must verify its own configuration.
+## Resource definition
 
-This is not the 1.0 capability catalog. Planned features are listed in docs/implementation-status.md of the adula-kit source repository; do not assume them.
+| Field type | Storage |
+|---|---|
+| string | varchar |
+| text | text |
+| integer | integer |
+| money | bigint minor units, decimal string in JSON |
+| boolean | boolean |
+| date | date (YYYY-MM-DD) |
+| datetime | timestamptz |
+| json | jsonb |
+| attachment | attachments row id; per-field accept/maxSize |
+| belongsTo | foreign key, preloaded, restrict on delete |
+| hasMany | child resource; inline rows saved with the parent |
+| lookup | lookups group key |
 
-Core user invitations are available through `UserInvitations` and the `core.users/invite` permission. New standalone projects include an Arabic invitation Dialog, SMTP mail and single-use 24-hour acceptance links; recipients set their own passwords and receive no automatic roles. Configure SMTP and APP_URL, then assign business roles after acceptance. Existing consumers must merge project-owned routes/pages deliberately.
+Field options: required, unique (partial, active rows), sortable, searchable (generated tsvector), filterable, permissionLevel, sequence, column.
 
-Administrative mutations protect the last active administrator and the acting administrator's own access. Repeated installation repairs missing bootstrap grants. The reference settings screen controls Gregorian, Umm al-Qura Hijri or dual-calendar presentation, edit-dialog dismissal confirmation and restrained transitions. Storage and API dates stay canonical. Permission actions require confirmation and report server outcomes.
+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.
 
-The separate @adula/create-app package creates a complete application from an empty directory, including local service provisioning, fresh migrations, an administrator and company identity intake. Node/npm and Docker for the default service mode are prerequisites; existing PostgreSQL/Redis can be used instead. The packages are published on npm under the experimental `alpha` tag: `npm create @adula/app@alpha my-app`.
+Role rule conditions: $eq, $ne, $in, $lt, $gt, $like on scalar fields; unsupported conditions are refused. Organization scope is always added with AND.
+
+Workflow steps: condition, update, notify, approval, delay, http, end.
+
+## Services
+
+- **Resources and authorization:** `defineResource`, `ResourceRegistry`, `ResourceService`, `createResourceController`, `buildAbility`, `accessibleBy`, `ActorStore`, `packedResourceRules`
+- **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`
+- **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
+- Page override: inertia/pages/<resource>/{index,form,show}.tsx replaces the generated page
+- 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
+
+## Outside the kit
+
+- Dynamic fields or a field editor screen
+- Runtime plugins
+- A visual workflow editor
+- Multi-tenant SaaS in one database (one deployment per organization)
+- XLSX import until a maintained parser passes the dependency rule (GAP-006)

package/build/agent/skills/idea-review/SKILL.md

@@ -3,4 +3,29 @@ name: idea-review
 description: Translate a new module or workflow into existing kit resources and declared extension points before writing code.
 ---
 
-Read docs/decisions, the resource registry, capabilities and KIT_GAPS.md. Identify existing entities before proposing new ones. Produce a compact module blueprint with owned tables, explicit scope, dependencies, relationships, events, field visibility and acceptance tests. Classify each requirement as implemented now, a declared extension, or outside the kit. Do not design a dynamic field editor, runtime plugin loader or visual workflow editor. A user's already-approved plan authorizes its specified reference modules; do not ask to approve them again.
+Use for a new module or workflow only; field changes do not need it.
+
+1. Run `node ace adula:capabilities` and read the output: kit field types, services,
+   workflow steps, extension points, what is outside the kit, and this project's
+   registered modules, resources and workflows. Read docs/decisions and KIT_GAPS.md.
+2. Find existing entities with the same meaning; reference them with belongsTo.
+   Never duplicate a table owned by another module.
+3. Produce a compact blueprint:
+   - module name, `dependsOn`, owned resources with `scoped` stated explicitly;
+   - fields with kit types, required/unique/searchable/filterable, permission levels,
+     hidden fields, lookups (groups and keys) and sequences;
+   - submittable documents and their workflow as steps (condition, update, notify,
+     approval, delay, http, end) with approvers by role;
+   - events consumed and emitted, listeners (idempotent) and any webhooks;
+   - role rules per action, including conditions from the six operators;
+   - acceptance tests: 403/404/uniqueness/scope from the generator plus the
+     business rules.
+4. Classify each requirement: **now** (kit capability), **extension** (hooks, page
+   override, listener, workflow), or **outside the kit** (record it in KIT_GAPS.md
+   with Needed by, Tried, Blocked because, Proposed kit change, Workaround).
+5. Never design a dynamic field editor, runtime plugin loader, visual workflow editor
+   or a second tenant model. An already-approved plan authorizes its modules; do not
+   ask to approve them again.
+
+After implementation, run the reviewers: module-review, security-review,
+schema-review, ui-review and perf-review.

package/build/agent/skills/module-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: module-review
+description: Review a module's boundaries, dependencies, events and scope before merging.
+---
+
+Check, citing file and line for every finding:
+
+- The module lives in `app/modules/<name>` and is registered in `start/modules.ts`
+  after every module it depends on; `dependsOn` lists each module whose resources
+  it references. `ResourceRegistry.register` must accept the order.
+- It writes only its own tables. Cross-module effects happen in idempotent
+  listeners (`consumeEvent` + processed_events), never by importing another
+  module's controllers or services. Heavy listeners dispatch jobs.
+- Every resource declares `scoped`. Central (`scoped: false`) resources are
+  justified; scoped ones rely on the kit's organization scope, not custom filters.
+- Documents that need approval use `submittable: true` and a module workflow; the
+  operational status is a lookup separate from `docStatus`.
+- No kit service is re-implemented under another name (notify, sequence, settings,
+  assignments, comments, imports, webhooks, workflows).
+- Educational fixtures are not imported by the application.
+
+Verdict: accept, or a numbered list of blocking findings.

package/build/agent/skills/perf-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: perf-review
+description: Review queries, pagination and background work against the performance budget.
+---
+
+Budget (plan section 13): list with two relations p95 < 300 ms, form save < 200 ms,
+cached Ability build < 5 ms, on 100,000 seeded rows and 50 concurrent users.
+
+Check, citing file and line:
+
+- Lists go through `ResourceService.list`: keyset pagination, limit ≤ 100, selected
+  columns only, belongsTo preloaded in one query per relation; no query in a loop.
+- Custom queries have supporting indexes (foreign keys, `(org_unit_id, deleted_at)`,
+  sort columns used by saved views); `EXPLAIN` shows no sequential scan on large
+  tables for the common filters.
+- Save paths keep one transaction: record, lines, activity, field changes and outbox.
+  Anything slow (mail, HTTP, PDF, imports) runs in the worker, never inline.
+- Listeners are idempotent and cheap or dispatch jobs; workflows do not poll.
+- Caches (Ability, lookups, settings) are invalidated by the kit's revision rules,
+  not by time alone.
+- Run `pnpm test:medical` with `K6_BINARY` on staging-like hardware before release
+  and record the measured p95 values; never relax the thresholds.
+
+Verdict: accept, or findings with the measurement or query plan.

package/build/agent/skills/schema-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: schema-review
+description: Review migrations and resource definitions for integrity and evolution.
+---
+
+Check, citing file and line:
+
+- Migrations are additive (expand/contract): no drop or rename of a column still
+  read by the previous release; kit migrations are never edited after release.
+- Standard columns come from the generator (`id`, `org_unit_id` when scoped,
+  `created_by`, `updated_by`, timestamps, `deleted_at`, `version`, `doc_status`,
+  `amended_from_id`); they are not hand-edited.
+- Every foreign key is indexed and `restrict` on delete (cascade only inside the
+  same module); `(org_unit_id, deleted_at)` exists for scoped tables.
+- Unique rules are partial (`WHERE deleted_at IS NULL`); searchable fields produce
+  the generated tsvector with a GIN index.
+- Money is bigint minor units; dates use `date`, instants `timestamptz`; changeable
+  lists are lookups, numbering uses sequences.
+- The definition's `form`, `list`, `show` and `serialize` match the columns, and
+  generated contract tests cover 403/404/uniqueness/scope.
+
+Verdict: accept, or blocking findings with the corrected migration.

package/build/agent/skills/security-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: security-review
+description: Review authorization, serialization and sensitive flows of a change.
+---
+
+Check, citing file and line:
+
+- Every route passes authentication and the resource goes through ResourceService
+  (or `resources.access` for record features). Custom queries use `accessibleBy`;
+  nothing reads records by id without the scope and Ability checks.
+- Responses use the kit serializers; hidden and `permissionLevel` fields never leave
+  the server, including through search, sort, filters, exports, prints, history,
+  notifications, webhooks and OpenAPI.
+- Role rules use only the six operators; nothing widens scope with an allow rule.
+- No hand-written crypto, sessions, password or token handling. Secrets are sealed
+  with the application encryption; tokens and recovery codes are stored hashed.
+- Outgoing HTTP (webhooks, workflow steps) targets HTTPS and cannot reach private
+  addresses in production; payloads carry identifiers, not record fields.
+- Uploads and imports are size-limited and parsed by the kit; errors never echo
+  secrets. Rate limits cover authentication, second factor and token creation.
+- 2FA, impersonation and authentication changes are flagged for human review
+  (AGENTS rule 11); map the change to ASVS 4.0.3 V2/V3/V4 items.
+
+Verdict: accept, or blocking findings with the exploit scenario for each.

package/build/agent/skills/ui-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: ui-review
+description: Review pages and components for RTL, the component system and data access.
+---
+
+Check, citing file and line:
+
+- Components come from `inertia/components/ui` (installed by `node ace adula:ui add`);
+  no `shadcn add` in modules, no hand-styled native controls or homemade dialogs.
+- Forms and record details use the shadcn Dialog (ResourceSurface) unless the user
+  asked otherwise; destructive actions confirm; edits guard against closing.
+- RTL: `dir="rtl"`, logical properties (`ms-`, `ps-`, `text-start`), arrows follow
+  the reading direction, Latin digits in amounts per the UI preference, Arabic
+  labels and English identifiers. Dates honor the calendar preference.
+- Generated pages are overridden only through `pages/<resource>/<mode>.tsx`.
+- Heavy sections are deferred props or fetched after render; lists paginate with
+  the scroll prop; no page renders data the server did not serialize for the user.
+- Accessible names exist for icon buttons, dialogs and regions; errors use
+  `role="alert"`; focus stays inside dialogs.
+- Company identity from docs/design-identity.md is applied, not invented.
+
+Verdict: accept, or findings with screenshots or selectors.

package/build/commands/capabilities.d.ts

@@ -2,5 +2,9 @@ import { BaseCommand } from '@adonisjs/core/ace';
 export default class Capabilities extends BaseCommand {
     static commandName: string;
     static description: string;
+    static options: {
+        startApp: boolean;
+    };
+    write: boolean;
     run(): Promise<void>;
 }

package/build/commands/capabilities.js

@@ -1,9 +1,40 @@
-import { BaseCommand } from '@adonisjs/core/ace';
-import { readFile } from 'node:fs/promises';
+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, flags } from '@adonisjs/core/ace';
+import { writeFile } from 'node:fs/promises';
+import { capabilityCatalog } from '../src/commands/capabilities.js';
 export default class Capabilities extends BaseCommand {
     static commandName = 'adula:capabilities';
-    static description = 'Print implemented capabilities and current acceptance boundary';
+    static description = 'Generate the capability catalog (kit features plus this project registry)';
+    static options = { startApp: true };
     async run() {
-        this.logger.log(await readFile(new URL('../agent/capabilities.md', import.meta.url), 'utf8'));
+        let registry;
+        try {
+            ;
+            ({ registry } = await this.app.import('#start/modules'));
+        }
+        catch {
+            this.logger.warning('start/modules could not be loaded; printing kit capabilities only');
+        }
+        // Imported lazily: main.ts lists this command itself.
+        const { getMetaData } = await import('./main.js');
+        const metadata = await getMetaData();
+        const catalog = capabilityCatalog({
+            registry,
+            commands: metadata.map((command) => `${command.commandName} — ${command.description}`),
+        });
+        if (this.write) {
+            await writeFile(this.app.makePath('capabilities.md'), catalog);
+            this.logger.success('capabilities.md');
+        }
+        else
+            this.logger.log(catalog);
     }
 }
+__decorate([
+    flags.boolean({ description: 'Write capabilities.md at the project root' })
+], Capabilities.prototype, "write", void 0);

package/build/commands/main.d.ts

@@ -1,6 +1,8 @@
+import Resource from './resource.js';
 import Doctor from './doctor.js';
-import Capabilities from './capabilities.js';
+import ModuleAdd from './module_add.js';
+import Ui from './ui.js';
 export declare function getMetaData(): Promise<import("@adonisjs/core/types/ace").CommandMetaData[]>;
 export declare function getCommand(meta: {
     commandName: string;
-}): Promise<typeof Capabilities | typeof Doctor | null>;
+}): Promise<typeof Resource | typeof Doctor | typeof ModuleAdd | typeof Ui | null>;

package/build/database/migrations/1770000000004_kit_collaboration.d.ts

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

package/build/database/migrations/1770000000004_kit_collaboration.js

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

package/build/database/migrations/1770000000005_kit_assignments.d.ts

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

package/build/database/migrations/1770000000005_kit_assignments.js

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

package/build/database/migrations/1770000000006_kit_messaging.d.ts

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

package/build/database/migrations/1770000000006_kit_messaging.js

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

package/build/database/migrations/1770000000007_kit_webhooks.d.ts

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

package/build/database/migrations/1770000000007_kit_webhooks.js

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

package/build/database/migrations/1770000000008_kit_imports.d.ts

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

package/build/database/migrations/1770000000008_kit_imports.js

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

package/build/database/migrations/1770000000010_kit_workflows.d.ts

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

package/build/database/migrations/1770000000010_kit_workflows.js

@@ -0,0 +1,10 @@
+import { BaseSchema } from '@adonisjs/lucid/schema';
+import { createWorkflowSchema } from '../../src/database/schema.js';
+export default class KitWorkflows extends BaseSchema {
+    async up() {
+        await createWorkflowSchema(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

@@ -14,7 +14,25 @@ export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js'
 export { ResourceService } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
-export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, } 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 { WorkflowEngine, workflowListeners } from './src/workflows/engine.js';
+export type { WorkflowRun, WorkflowRunStatus, WorkflowOptions } 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 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 { 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 { migrateStorage } from './src/attachments/storage_migrate.js';
@@ -49,3 +67,5 @@ export { runtimeHealth, isBackupStale, backupStale, heartbeat, HEARTBEAT_MAX_AGE
 export type { RuntimeHealth, HeartbeatStatus, QueueSnapshot, QueueCounts, FailedJob, } from './src/core/health.js';
 export { MailDeliveryTest, MAIL_TEST_KEY, type MailTestState } from './src/core/mail_test.js';
 export { InitialSetup, type SetupCheck } from './src/core/setup.js';
+export { KIT_VERSION } from './src/version.js';
+export { capabilityCatalog, SERVICES as CAPABILITY_SERVICES, FIELD_TYPES, WORKFLOW_STEPS, } from './src/commands/capabilities.js';

package/build/index.js

@@ -10,7 +10,16 @@ export { accessibleBy, authorizationSql, conditionSql } from './src/auth/sql.js'
 export { ResourceService } from './src/admin/resource_service.js';
 export { serialize, writableInput, selectedFields } from './src/admin/contracts.js';
 export { KitError } from './src/admin/errors.js';
-export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, } from './src/database/schema.js';
+export { createCoreSchema, createResourceTable, createAttachmentsSchema, createSavedViewsSchema, createCollaborationSchema, createAssignmentsSchema, createMessagingSchema, createWebhooksSchema, createImportsSchema, createWorkflowSchema, } 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 { 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 { migrateStorage } from './src/attachments/storage_migrate.js';
 export { diagnoseAttachments } from './src/attachments/doctor.js';
@@ -32,3 +41,5 @@ export { SettingsAdmin, isProtectedSetting, parseSettingValue, SETTING_SCOPES, P
 export { runtimeHealth, isBackupStale, backupStale, heartbeat, HEARTBEAT_MAX_AGE_MS, BACKUP_MAX_AGE_MS, } from './src/core/health.js';
 export { MailDeliveryTest, MAIL_TEST_KEY } from './src/core/mail_test.js';
 export { InitialSetup } from './src/core/setup.js';
+export { KIT_VERSION } from './src/version.js';
+export { capabilityCatalog, SERVICES as CAPABILITY_SERVICES, FIELD_TYPES, WORKFLOW_STEPS, } from './src/commands/capabilities.js';

package/build/src/admin/contracts.js

@@ -19,18 +19,27 @@ export function selectedFields(resource, ability, options = {}) {
         ]),
     ].filter((key) => key !== 'orgPath' && resource.fields[key]?.type !== 'hasMany');
 }
+const rowKeys = new WeakMap();
+/** Record keys and their columns for a resource, computed once per definition. */
+function keysOf(resource) {
+    let keys = rowKeys.get(resource);
+    if (!keys) {
+        keys = [
+            ...standard,
+            'orgUnitId',
+            'version',
+            'docStatus',
+            'amendedFromId',
+            'orgPath',
+            ...Object.keys(resource.fields),
+        ].map((key) => [key, resource.fields[key]?.column ?? columnName(key)]);
+        rowKeys.set(resource, keys);
+    }
+    return keys;
+}
 export function fromRow(row, resource) {
     const result = {};
-    for (const key of [
-        ...standard,
-        'orgUnitId',
-        'version',
-        'docStatus',
-        'amendedFromId',
-        'orgPath',
-        ...Object.keys(resource.fields),
-    ]) {
-        const column = resource.fields[key]?.column ?? columnName(key);
+    for (const [key, column] of keysOf(resource)) {
         if (column in row) {
             const value = row[column];
             result[key] =

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

@@ -22,6 +22,7 @@ export interface ResourceController {
     destroy(ctx: HttpContext): Promise<unknown>;
     submit(ctx: HttpContext): Promise<unknown>;
     cancel(ctx: HttpContext): Promise<unknown>;
+    amend(ctx: HttpContext): Promise<unknown>;
     create(ctx: HttpContext): Promise<unknown>;
     edit(ctx: HttpContext): Promise<unknown>;
     options(ctx: HttpContext): Promise<unknown>;

package/build/src/admin/controller.js

@@ -27,6 +27,7 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
                     sort: ctx.request.input('sort'),
                     direction: ctx.request.input('direction'),
                     filters: ctx.request.input('filters'),
+                    tag: ctx.request.input('tag'),
                     estimate: ctx.request.input('estimate') !== 'false' && ctx.request.input('estimate') !== false,
                 });
                 return renderList && ctx.request.accepts(['html', 'json']) === 'html'
@@ -70,6 +71,11 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
         async cancel(ctx) {
             return this.#transition(ctx, 'cancel');
         }
+        async amend(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => ctx.response.created({
+                data: await resources.amend(resource.name, this.#id(ctx), actor),
+            }));
+        }
         #id(ctx) {
             return this.#positiveId(ctx.params.id);
         }

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

@@ -10,6 +10,8 @@ export type ListOptions = {
     sort?: string;
     direction?: 'asc' | 'desc';
     filters?: Record<string, unknown>;
+    /** Only records carrying this tag (see RecordCollaboration.setTags). */
+    tag?: string;
     estimate?: boolean;
 };
 /**
@@ -21,6 +23,8 @@ export declare class ResourceService {
     private db;
     private registry;
     constructor(db: Knex, registry: ResourceRegistry);
+    /** The Arabic label of a registered resource, for notifications and titles. */
+    label(name: string): string;
     /** Project navigation is derived from registered resources and the current actor. */
     navigation(actor: Actor): ResourceNavigation;
     describe(name: string, actor: Actor): ResourceDescription;
@@ -34,6 +38,17 @@ export declare class ResourceService {
     private columns;
     private find;
     private requireRecord;
+    /**
+     * Authorizes one record for collaboration features (comments, tags, assignments...).
+     * Scope and conditional rules apply exactly as for show/update.
+     */
+    access(name: string, id: number, actor: Actor, action?: Action, db?: Knex): Promise<{
+        resource: Resource;
+        record: RecordData;
+        ability: KitAbility;
+    }>;
+    /** Whether a (possibly other) actor may perform an action on a record; never throws for denial. */
+    permits(name: string, id: number, actor: Actor, action?: Action): Promise<boolean>;
     list(name: string, actor: Actor, options?: ListOptions): Promise<{
         data: SerializedRecord[];
         permissions: {
@@ -190,5 +205,11 @@ export declare class ResourceService {
     /** Inline children share the parent's draft state, organization and update authority. */
     private requireInlineParents;
     transition(name: string, id: number, actor: Actor, action: 'delete' | 'submit' | 'cancel', version?: unknown, transaction?: Knex.Transaction): Promise<SerializedRecord>;
+    /**
+     * 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.
+     */
+    amend(name: string, id: number, actor: Actor, transaction?: Knex.Transaction): Promise<SerializedRecord>;
     private audit;
 }