@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/collaboration/record_collaboration.js

@@ -0,0 +1,348 @@
+import { subject } from '@casl/ability';
+import { jsonValue } from '../admin/contracts.js';
+import { KitError } from '../admin/errors.js';
+import { notifyWithTemplate } from '../core/message_templates.js';
+const BODY_LIMIT = 5000;
+const MENTION_LIMIT = 20;
+const TAG_LIMIT = 20;
+const TAG_PATTERN = /^[\p{L}\p{N}][\p{L}\p{N} _-]{0,59}$/u;
+/** Minimum permission level of a field for the current resource definition. */
+function fieldLevel(resource, key) {
+    return Math.max(resource.fields[key]?.permissionLevel ?? 0, resource.hidden?.includes(key) ? 1 : 0);
+}
+function readableField(resource, record, ability, actor, key) {
+    const serialized = resource.serialize ?? [...resource.list, ...resource.show];
+    return (key in resource.fields &&
+        serialized.includes(key) &&
+        actor.permissionLevel >= fieldLevel(resource, key) &&
+        ability.can('view', subject(resource.name, record), key));
+}
+/**
+ * Collaboration around a record: comments with mentions, followers, tags and the
+ * per-field change history. Every read and write re-authorizes the record itself
+ * through ResourceService, so these features can never widen record access.
+ */
+export class RecordCollaboration {
+    db;
+    resources;
+    actors;
+    constructor(db, resources, actors) {
+        this.db = db;
+        this.resources = resources;
+        this.actors = actors;
+    }
+    async state(name, id, actor) {
+        const { resource, record, ability } = await this.resources.access(name, id, actor);
+        const rows = await this.db('comments as c')
+            .leftJoin('users as u', 'u.id', 'c.author_id')
+            .where({ 'c.resource': name, 'c.record_id': id })
+            .whereNull('c.deleted_at')
+            .orderBy('c.id', 'desc')
+            .limit(51)
+            .select('c.*', 'u.full_name as author_name');
+        const page = rows.slice(0, 50);
+        const mentions = page.length
+            ? await this.db('comment_mentions as m')
+                .join('users as u', 'u.id', 'm.user_id')
+                .whereIn('m.comment_id', page.map((row) => row.id))
+                .select('m.comment_id', 'u.id', 'u.full_name')
+            : [];
+        const tags = await this.tags(name, id);
+        const follow = await this.db('followers')
+            .where({ resource: name, record_id: id })
+            .select(this.db.raw('count(*)::int as count'), this.db.raw('bool_or(user_id = ?) as own', [actor.id]))
+            .first();
+        return {
+            comments: page.reverse().map((row) => ({
+                id: Number(row.id),
+                body: String(row.body),
+                authorId: Number(row.author_id),
+                authorName: row.author_name ? String(row.author_name) : null,
+                mentions: mentions
+                    .filter((mention) => Number(mention.comment_id) === Number(row.id))
+                    .map((mention) => ({ id: Number(mention.id), name: String(mention.full_name ?? '') })),
+                createdAt: new Date(row.created_at).toISOString(),
+                editedAt: row.edited_at ? new Date(row.edited_at).toISOString() : null,
+                own: Number(row.author_id) === actor.id,
+            })),
+            hasMoreComments: rows.length > 50,
+            tags,
+            following: Boolean(follow?.own),
+            followers: Number(follow?.count ?? 0),
+            changes: await this.readChanges(resource, record, ability, actor, id),
+            canComment: true,
+            canTag: resource.actions.includes('update') &&
+                (await this.resources.permits(name, id, actor, 'update')),
+        };
+    }
+    async readChanges(resource, record, ability, actor, id) {
+        const rows = await this.db('field_changes as f')
+            .join('activities as a', 'a.id', 'f.activity_id')
+            .leftJoin('users as u', 'u.id', 'a.actor_id')
+            .where({ 'f.resource': resource.name, 'f.record_id': id })
+            .orderBy('f.id', 'desc')
+            .limit(200)
+            .select('f.*', 'a.created_at', 'u.full_name as actor_name');
+        // Values are filtered per viewer: a private field's history is as private as the field.
+        return rows
+            .filter((row) => readableField(resource, record, ability, actor, String(row.field)))
+            .slice(0, 100)
+            .map((row) => ({
+            id: Number(row.id),
+            field: String(row.field),
+            before: jsonValue(row.before),
+            after: jsonValue(row.after),
+            actorName: row.actor_name ? String(row.actor_name) : null,
+            createdAt: new Date(row.created_at).toISOString(),
+        }));
+    }
+    async comment(name, id, actor, input) {
+        await this.resources.access(name, id, actor);
+        const body = typeof input.body === 'string' ? input.body.trim() : '';
+        if (!body || body.length > BODY_LIMIT)
+            throw new KitError(422, 'E_COMMENT_BODY', 'نص التعليق مطلوب ولا يتجاوز 5000 حرف');
+        const requested = this.userIds(input.mentions);
+        // Mentioning someone who cannot read the record would leak it through the notification.
+        const mentioned = [];
+        for (const userId of requested) {
+            if (userId === actor.id)
+                continue;
+            if (await this.canView(name, id, userId))
+                mentioned.push(userId);
+            else
+                throw new KitError(422, 'E_MENTION', 'لا يمكن الإشارة إلى مستخدم لا يملك صلاحية عرض السجل');
+        }
+        return this.db.transaction(async (trx) => {
+            const [row] = await trx('comments')
+                .insert({ resource: name, record_id: id, author_id: actor.id, body })
+                .returning('*');
+            if (mentioned.length)
+                await trx('comment_mentions').insert(mentioned.map((userId) => ({ comment_id: row.id, user_id: userId })));
+            await trx('followers')
+                .insert({ resource: name, record_id: id, user_id: actor.id })
+                .onConflict(['resource', 'record_id', 'user_id'])
+                .ignore();
+            const author = await trx('users').where('id', actor.id).first('full_name');
+            const authorName = author?.full_name ? String(author.full_name) : `مستخدم #${actor.id}`;
+            const label = this.label(name);
+            for (const userId of mentioned)
+                await notifyWithTemplate(trx, userId, 'comment.mentioned', { author: authorName, resource: label, id, excerpt: body.slice(0, 200) }, undefined, { resource: name, recordId: id });
+            const followers = await trx('followers')
+                .where({ resource: name, record_id: id })
+                .whereNot('user_id', actor.id)
+                .whereNotIn('user_id', mentioned.length ? mentioned : [0])
+                .pluck('user_id');
+            for (const userId of followers) {
+                if (!(await this.canView(name, id, Number(userId))))
+                    continue;
+                await notifyWithTemplate(trx, Number(userId), 'comment.created', { author: authorName, resource: label, id, excerpt: body.slice(0, 200) }, undefined, { resource: name, recordId: id });
+            }
+            const names = mentioned.length
+                ? await trx('users').whereIn('id', mentioned).select('id', 'full_name')
+                : [];
+            return {
+                id: Number(row.id),
+                body,
+                authorId: actor.id,
+                authorName: author?.full_name ? String(author.full_name) : null,
+                mentions: names.map((user) => ({
+                    id: Number(user.id),
+                    name: String(user.full_name ?? ''),
+                })),
+                createdAt: new Date(row.created_at).toISOString(),
+                editedAt: null,
+                own: true,
+            };
+        });
+    }
+    /** Authors edit or remove their own comments while they can still read the record. */
+    async editComment(name, id, comment, actor, body) {
+        await this.resources.access(name, id, actor);
+        const commentId = this.commentId(comment);
+        const text = typeof body === 'string' ? body.trim() : '';
+        if (!text || text.length > BODY_LIMIT)
+            throw new KitError(422, 'E_COMMENT_BODY', 'نص التعليق مطلوب ولا يتجاوز 5000 حرف');
+        const updated = await this.db('comments')
+            .where({ id: commentId, resource: name, record_id: id, author_id: actor.id })
+            .whereNull('deleted_at')
+            .update({ body: text, edited_at: this.db.fn.now() });
+        if (!updated)
+            throw new KitError(404, 'E_COMMENT_NOT_FOUND', 'التعليق غير موجود');
+    }
+    async deleteComment(name, id, comment, actor) {
+        await this.resources.access(name, id, actor);
+        const commentId = this.commentId(comment);
+        const deleted = await this.db('comments')
+            .where({ id: commentId, resource: name, record_id: id, author_id: actor.id })
+            .whereNull('deleted_at')
+            .update({ deleted_at: this.db.fn.now() });
+        if (!deleted)
+            throw new KitError(404, 'E_COMMENT_NOT_FOUND', 'التعليق غير موجود');
+    }
+    async follow(name, id, actor, following) {
+        await this.resources.access(name, id, actor);
+        if (following)
+            await this.db('followers')
+                .insert({ resource: name, record_id: id, user_id: actor.id })
+                .onConflict(['resource', 'record_id', 'user_id'])
+                .ignore();
+        else
+            await this.db('followers').where({ resource: name, record_id: id, user_id: actor.id }).del();
+    }
+    /** Replaces the record's tags. Tagging changes how a record is found, so it needs update. */
+    async setTags(name, id, actor, input) {
+        const { resource } = await this.resources.access(name, id, actor);
+        if (!resource.actions.includes('update'))
+            throw new KitError(403, 'E_FORBIDDEN', 'ليس لديك صلاحية لهذا الإجراء');
+        await this.resources.access(name, id, actor, 'update');
+        if (!Array.isArray(input) || input.length > TAG_LIMIT)
+            throw new KitError(422, 'E_TAGS', 'الوسوم قائمة لا تتجاوز 20 وسماً');
+        const names = [
+            ...new Set(input.map((tag) => {
+                const value = typeof tag === 'string' ? tag.trim() : '';
+                if (!TAG_PATTERN.test(value))
+                    throw new KitError(422, 'E_TAGS', 'الوسم حروف وأرقام ومسافات فقط ولا يتجاوز 60 حرفاً');
+                return value;
+            })),
+        ];
+        await this.db.transaction(async (trx) => {
+            if (names.length)
+                await trx('tags')
+                    .insert(names.map((tag) => ({ name: tag })))
+                    .onConflict('name')
+                    .ignore();
+            const ids = names.length ? await trx('tags').whereIn('name', names).pluck('id') : [];
+            await trx('taggables').where({ resource: name, record_id: id }).del();
+            if (ids.length)
+                await trx('taggables').insert(ids.map((tagId) => ({ tag_id: tagId, resource: name, record_id: id })));
+        });
+        return this.tags(name, id);
+    }
+    async tags(name, id) {
+        const names = await this.db('taggables as t')
+            .join('tags', 'tags.id', 't.tag_id')
+            .where({ 't.resource': name, 't.record_id': id })
+            .orderBy('tags.name')
+            .pluck('tags.name');
+        return names.map(String);
+    }
+    /** Tag vocabulary used on records of a resource the actor may list. */
+    async tagOptions(name, actor) {
+        this.resources.describe(name, actor);
+        const names = await this.db('taggables as t')
+            .join('tags', 'tags.id', 't.tag_id')
+            .where('t.resource', name)
+            .distinct('tags.name')
+            .orderBy('tags.name')
+            .limit(200)
+            .pluck('tags.name');
+        return names.map(String);
+    }
+    /** Active users that may read the record, for the mention picker. */
+    async mentionCandidates(name, id, actor, search = '') {
+        await this.resources.access(name, id, actor);
+        const term = String(search).trim().slice(0, 60);
+        const result = [];
+        // Readers are filtered per user, so page through candidates until ten readers
+        // are found; a bounded scan keeps a large directory from turning into a sweep.
+        const page = 100;
+        for (let offset = 0; result.length < 10 && offset < 2000; offset += page) {
+            const query = this.db('users')
+                .whereNot('id', actor.id)
+                .whereNull('disabled_at')
+                .orderBy([{ column: 'full_name' }, { column: 'id' }])
+                .offset(offset)
+                .limit(page)
+                .select('id', 'full_name');
+            if (term)
+                query.where((where) => where.whereILike('full_name', `%${term}%`).orWhereILike('email', `${term}%`));
+            const users = await query;
+            for (const user of users) {
+                if (result.length >= 10)
+                    break;
+                if (await this.canView(name, id, Number(user.id)))
+                    result.push({ id: Number(user.id), name: String(user.full_name ?? `#${user.id}`) });
+            }
+            if (users.length < page)
+                break;
+        }
+        return result;
+    }
+    /**
+     * Listener factory: followers hear about updates and document transitions of the
+     * records they follow, but only while they can still read the record.
+     */
+    followerListener(module, resource, event) {
+        return {
+            name: `kit.followers.${module}.${resource}.${event}`,
+            event: `${module}.${resource}.${event}`,
+            handle: async (domainEvent, trx) => {
+                const id = Number(domainEvent.payload.id);
+                const actorId = Number(domainEvent.payload.actorId);
+                const followers = await trx('followers')
+                    .where({ resource, record_id: id })
+                    .whereNot('user_id', actorId)
+                    .pluck('user_id');
+                const verbs = {
+                    updated: 'تم تعديل',
+                    submitted: 'تم اعتماد',
+                    cancelled: 'تم إلغاء',
+                    deleted: 'تم حذف',
+                };
+                for (const userId of followers) {
+                    if (event !== 'deleted' && !(await this.canView(resource, id, Number(userId))))
+                        continue;
+                    await notifyWithTemplate(trx, Number(userId), 'record.changed', { change: verbs[event] ?? 'تحديث', resource: this.label(resource), id }, undefined, 
+                    // A deleted record has no page to open.
+                    event === 'deleted' ? null : { resource, recordId: id });
+                }
+            },
+        };
+    }
+    label(name) {
+        try {
+            return this.resources.label(name);
+        }
+        catch {
+            return name;
+        }
+    }
+    async canView(name, id, userId) {
+        const disabled = await this.db('users').where('id', userId).first('disabled_at');
+        if (!disabled || disabled.disabled_at)
+            return false;
+        return this.resources.permits(name, id, await this.actors.load(userId));
+    }
+    /** Parsed after the record is authorized, so malformed ids never bypass the 403. */
+    commentId(value) {
+        const id = Number(value);
+        if (!Number.isSafeInteger(id) || id <= 0)
+            throw new KitError(404, 'E_COMMENT_NOT_FOUND', 'التعليق غير موجود');
+        return id;
+    }
+    userIds(value) {
+        if (value === undefined || value === null)
+            return [];
+        if (!Array.isArray(value) || value.length > MENTION_LIMIT)
+            throw new KitError(422, 'E_MENTION', 'الإشارات قائمة لا تتجاوز 20 مستخدماً');
+        return [
+            ...new Set(value.map((entry) => {
+                const id = Number(entry);
+                if (!Number.isSafeInteger(id) || id <= 0)
+                    throw new KitError(422, 'E_MENTION', 'معرّف المستخدم غير صالح');
+                return id;
+            })),
+        ];
+    }
+}
+/** Follower notifications for every registered resource's update and document events. */
+export function followerListeners(registry, collaboration) {
+    return registry.all().flatMap((resource) => ['updated', 'submitted', 'cancelled', 'deleted'].map((event) => {
+        const module = registry.owner(resource.name);
+        return {
+            name: `kit.followers.${module}.${resource.name}.${event}`,
+            event: `${module}.${resource.name}.${event}`,
+            handle: (domainEvent, trx) => collaboration().followerListener(module, resource.name, event).handle(domainEvent, trx),
+        };
+    }));
+}

package/build/src/commands/agent_assets.js

@@ -16,6 +16,11 @@ export async function agentAssets() {
     for (const [source, target] of [
         ['idea-review', 'adula-idea-review'],
         ['adula-frontend-design', 'adula-frontend-design'],
+        ['module-review', 'adula-module-review'],
+        ['security-review', 'adula-security-review'],
+        ['schema-review', 'adula-schema-review'],
+        ['ui-review', 'adula-ui-review'],
+        ['perf-review', 'adula-perf-review'],
     ]) {
         skills[`.agents/skills/${target}/SKILL.md`] = await readFile(new URL(`../../agent/skills/${source}/SKILL.md`, import.meta.url), 'utf8');
     }

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

@@ -0,0 +1,19 @@
+import type { ResourceRegistry } from '../resource/registry.js';
+/** Field kinds accepted by defineResource, with their storage. */
+export declare const FIELD_TYPES: Record<string, string>;
+export declare const FIELD_OPTIONS: string[];
+export declare const RESOURCE_OPTIONS: string[];
+export declare const CONDITION_OPERATORS: string[];
+export declare const WORKFLOW_STEPS: string[];
+/**
+ * Kit services by concern. Every name is a public export of @adula/kit; a test
+ * checks this list against the package entry so the catalog cannot drift.
+ */
+export declare const SERVICES: Record<string, string[]>;
+export declare const EXTENSION_POINTS: string[];
+export declare const OUTSIDE_THE_KIT: string[];
+/** The capability catalog read by idea-review: generated, never hand-edited. */
+export declare function capabilityCatalog(options?: {
+    registry?: ResourceRegistry;
+    commands?: string[];
+}): string;

package/build/src/commands/capabilities.js

@@ -0,0 +1,179 @@
+import { KIT_VERSION } from '../version.js';
+import { WORKFLOW_NAME_RULE } from '../workflows/define_workflow.js';
+import { ACTOR_ID } from '../auth/conditions.js';
+/** Field kinds accepted by defineResource, with their storage. */
+export const FIELD_TYPES = {
+    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',
+    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',
+};
+export const FIELD_OPTIONS = [
+    'required',
+    'unique (partial, active rows)',
+    'sortable',
+    'searchable (generated tsvector)',
+    'filterable',
+    'permissionLevel',
+    'sequence',
+    'column',
+];
+export const 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',
+];
+export const CONDITION_OPERATORS = ['$eq', '$ne', '$in', '$lt', '$gt', '$like'];
+export const WORKFLOW_STEPS = [
+    'condition',
+    'update',
+    'notify',
+    'approval',
+    'decision',
+    'delay',
+    'http',
+    'end',
+];
+/**
+ * Kit services by concern. Every name is a public export of @adula/kit; a test
+ * checks this list against the package entry so the catalog cannot drift.
+ */
+export const 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',
+        'InboundWebhooks',
+        'openApiDocument',
+        'ImportBatches',
+        'renderPrintHtml',
+        'htmlToPdf',
+    ],
+    'Security': ['UserInvitations', 'UsersAdmin', 'RolesAdmin'],
+    'Data and operations': [
+        'sequence',
+        'Settings',
+        'SettingsAdmin',
+        'publishOutbox',
+        'consumeEvent',
+        'recordMutation',
+        'moveOrgUnit',
+        'migrateStorage',
+        'verifyBackup',
+        'runtimeHealth',
+    ],
+};
+export const 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',
+];
+export const 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)',
+];
+/** The capability catalog read by idea-review: generated, never hand-edited. */
+export function capabilityCatalog(options = {}) {
+    const lines = [
+        `# adula-kit capabilities (${KIT_VERSION})`,
+        '',
+        'Generated by `node ace adula:capabilities`. Read this before proposing a module; anything not listed here is not provided by the kit.',
+        '',
+        '## Resource definition',
+        '',
+        '| Field type | Storage |',
+        '|---|---|',
+        ...Object.entries(FIELD_TYPES).map(([type, storage]) => `| ${type} | ${storage} |`),
+        '',
+        `Field options: ${FIELD_OPTIONS.join(', ')}.`,
+        '',
+        `Resource options: ${RESOURCE_OPTIONS.join(', ')}.`,
+        '',
+        `Role rule conditions: ${CONDITION_OPERATORS.join(', ')} 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: ${WORKFLOW_STEPS.join(', ')}. Workflow and step names: ${WORKFLOW_NAME_RULE} (for example release_approval, notify_approved).`,
+        '',
+        '## Services',
+        '',
+        ...Object.entries(SERVICES).map(([area, names]) => `- **${area}:** ${names.map((name) => `\`${name}\``).join(', ')}`),
+        '',
+        '## Extension points',
+        '',
+        ...EXTENSION_POINTS.map((point) => `- ${point}`),
+        '',
+        '## Outside the kit',
+        '',
+        ...OUTSIDE_THE_KIT.map((point) => `- ${point}`),
+    ];
+    if (options.commands?.length)
+        lines.push('', '## Commands', '', ...options.commands.map((command) => `- \`${command}\``));
+    if (options.registry) {
+        lines.push('', '## This project', '');
+        const modules = options.registry.modules();
+        if (!modules.length)
+            lines.push('No modules are registered yet.');
+        for (const module of modules) {
+            lines.push(`### ${module.name} — ${module.label.ar}`, '');
+            if (module.dependsOn.length)
+                lines.push(`Depends on: ${module.dependsOn.join(', ')}`, '');
+            for (const resource of module.resources)
+                lines.push(`- \`${resource.name}\` (${resource.label.ar}; ${resource.scoped ? 'scoped' : 'central'}${resource.submittable ? ', submittable' : ''}): ${Object.entries(resource.fields)
+                    .map(([key, field]) => `${key}:${field.type}${'resource' in field ? `→${field.resource}` : ''}`)
+                    .join(', ')}`);
+            for (const workflow of module.workflows ?? [])
+                lines.push(`- workflow \`${workflow.name}@${workflow.version}\` on ${workflow.resource}: ${Object.keys(workflow.steps).join(' → ')}`);
+            lines.push('');
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}

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

@@ -1,4 +1,7 @@
 import type { Settings } from '../services/settings.js';
+import type { Field, Resource } from '../resource/types.js';
+import type { WorkflowDefinition } from '../workflows/define_workflow.js';
+import type { RuntimeHealth } from '../core/health.js';
 export type Finding = {
     check: string;
     status: 'pass' | 'warn' | 'fail' | 'info';
@@ -9,3 +12,31 @@ export declare function diagnoseUploads(root: string): Promise<Finding>;
 export declare function diagnoseUi(root: string): Promise<Finding[]>;
 export declare function diagnoseAgentSkills(root: string): Promise<Finding>;
 export declare function diagnose(root: string, settings: Settings, production: boolean, env: Record<string, string | undefined>, now?: number): Promise<Finding[]>;
+type TableShape = Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields'> & {
+    fields: Record<string, Pick<Field, 'column' | 'required' | 'sequence' | 'unique' | 'searchable'> & {
+        type: string;
+        resource?: string;
+    }>;
+};
+/**
+ * A generated create-migration embeds the definition as it was at scaffold time. While it is
+ * still pending, compare that snapshot with the current resource so the table matches (#20).
+ */
+export declare function diagnoseResourceSnapshots(pending: {
+    file: string;
+    source: string;
+}[], resource: (name: string) => TableShape | undefined): Finding;
+/**
+ * Workflow recipients address roles by their stable key, or for compatibility by
+ * their editable display name. List references that match no role, and those that
+ * only match a display name, which a rename in the roles screen would break (#25).
+ */
+export declare function diagnoseWorkflowRoles(workflows: readonly Pick<WorkflowDefinition, 'name' | 'version' | 'steps'>[], roles: readonly (string | {
+    key: string | null;
+    name: string;
+})[]): Finding;
+/** Events wait in the outbox until a worker publishes them; a stale backlog means none runs (#50). */
+export declare function diagnoseOutbox(health: Pick<RuntimeHealth, 'outbox'> & {
+    heartbeats: Pick<RuntimeHealth['heartbeats'], 'worker'>;
+}): Finding;
+export {};