@endora-commerce/mod-admin-actions 0.100.0

package/dist/backend/services/admin-actions-reconciler.d.ts

@@ -0,0 +1,49 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { ModuleAction as ModuleActionDecl } from '@endora-commerce/contracts';
+/**
+ * Admin Actions Reconciler — feature 020.
+ *
+ * Idempotent UPSERT-and-prune of `module_actions` rows from a module's
+ * declared `manifest.actions` array. Mirrors feature 019's i18n-service
+ * UPSERT pattern: a single SQL statement with `INSERT … ON CONFLICT
+ * (module_id, action_id) DO UPDATE` so every successful install
+ * advances the per-row `version` sequence whether the row existed or
+ * not. After UPSERT, any rows owned by `moduleId` whose `action_id` is
+ * no longer in the new declaration are deleted (prune).
+ *
+ * Wraps work in the caller's transaction (the lifecycle orchestrator
+ * supplies its own `EntityManager`); idempotent — re-running install
+ * with the same payload is a no-op aside from bumping `version`.
+ */
+export interface AdminActionsReconcilerDeps {
+    em: () => EntityManager;
+}
+export declare class AdminActionsReconciler {
+    private readonly deps;
+    constructor(deps: AdminActionsReconcilerDeps);
+    /**
+     * Install (or update) every declared action for `moduleId`. After
+     * inserting/updating the declared rows, prune any rows for the same
+     * module whose action_id is not present in the new declaration.
+     */
+    installForModule(args: {
+        moduleId: string;
+        actions: readonly ModuleActionDecl[];
+        em?: EntityManager;
+    }): Promise<{
+        upserted: number;
+        pruned: number;
+    }>;
+    /**
+     * Hard-uninstall — drop every action row for the module. Soft-
+     * uninstall (state → 'disabled') intentionally leaves rows in place;
+     * visibility is gated by the registry-state join at query time.
+     */
+    removeForModule(args: {
+        moduleId: string;
+        em?: EntityManager;
+    }): Promise<{
+        removed: number;
+    }>;
+}
+//# sourceMappingURL=admin-actions-reconciler.d.ts.map

package/dist/backend/services/admin-actions-reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actions-reconciler.d.ts","sourceRoot":"","sources":["../../../src/backend/services/admin-actions-reconciler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAGnF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,aAAa,CAAC;CACzB;AAED,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,0BAA0B;IAE7D;;;;OAIG;IACG,gBAAgB,CAAC,IAAI,EAAE;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;QACrC,EAAE,CAAC,EAAE,aAAa,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA2DjD;;;;OAIG;IACG,eAAe,CAAC,IAAI,EAAE;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,EAAE,CAAC,EAAE,aAAa,CAAC;KACpB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAOjC"}

package/dist/backend/services/admin-actions-reconciler.js

@@ -0,0 +1,78 @@
+import { ModuleAction } from '../entities/module-action.entity.js';
+export class AdminActionsReconciler {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Install (or update) every declared action for `moduleId`. After
+     * inserting/updating the declared rows, prune any rows for the same
+     * module whose action_id is not present in the new declaration.
+     */
+    async installForModule(args) {
+        // command-coverage-ignore: idempotent lifecycle reconciler/seed — a system-
+        // invariant repair, not an operator-initiated audited write.
+        const targetEm = args.em ?? this.deps.em();
+        const declaredIds = new Set();
+        for (const action of args.actions) {
+            declaredIds.add(action.id);
+            // `targetEm.execute`, not `targetEm.getKnex().raw` — the knex instance is
+            // connection-level and carries no transaction context, so the UPSERT
+            // committed on its own connection while the prune below it (an
+            // `em.nativeDelete`) stayed inside the caller's transaction. One method,
+            // two answers to a rollback (issue #200).
+            await targetEm.execute(`insert into "module_actions" (` +
+                `"module_id", "action_id", "label_key", "description_key", "icon", ` +
+                `"target_route", "required_permission", "keywords", "weight", ` +
+                `"installed_at", "updated_at"` +
+                `) values (?, ?, ?, ?, ?, ?, ?, ?::jsonb, ?, now(), now()) ` +
+                `on conflict ("module_id", "action_id") do update set ` +
+                `"label_key" = excluded."label_key", ` +
+                `"description_key" = excluded."description_key", ` +
+                `"icon" = excluded."icon", ` +
+                `"target_route" = excluded."target_route", ` +
+                `"required_permission" = excluded."required_permission", ` +
+                `"keywords" = excluded."keywords", ` +
+                `"weight" = excluded."weight", ` +
+                `"version" = nextval('module_actions_version_seq'), ` +
+                `"updated_at" = now()`, [
+                args.moduleId,
+                action.id,
+                action.labelKey,
+                action.descriptionKey ?? null,
+                action.icon,
+                action.targetRoute,
+                action.requiredPermission ?? null,
+                JSON.stringify(action.keywords ?? []),
+                action.weight ?? 100,
+            ]);
+        }
+        // Prune: delete any rows for this module whose action_id is not in
+        // the newly-declared set. The empty-set case is safe — the
+        // whereNotIn(...) becomes a delete-all-for-module.
+        let pruned = 0;
+        if (declaredIds.size > 0) {
+            pruned = await targetEm.nativeDelete(ModuleAction, {
+                moduleId: args.moduleId,
+                actionId: { $nin: [...declaredIds] },
+            });
+        }
+        else {
+            pruned = await targetEm.nativeDelete(ModuleAction, { moduleId: args.moduleId });
+        }
+        return { upserted: args.actions.length, pruned };
+    }
+    /**
+     * Hard-uninstall — drop every action row for the module. Soft-
+     * uninstall (state → 'disabled') intentionally leaves rows in place;
+     * visibility is gated by the registry-state join at query time.
+     */
+    async removeForModule(args) {
+        // command-coverage-ignore: idempotent lifecycle reconciler/seed — a system-
+        // invariant repair, not an operator-initiated audited write.
+        const targetEm = args.em ?? this.deps.em();
+        const removed = await targetEm.nativeDelete(ModuleAction, { moduleId: args.moduleId });
+        return { removed };
+    }
+}
+//# sourceMappingURL=admin-actions-reconciler.js.map

package/dist/backend/services/admin-actions-reconciler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actions-reconciler.js","sourceRoot":"","sources":["../../../src/backend/services/admin-actions-reconciler.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAqBnE,MAAM,OAAO,sBAAsB;IACJ;IAA7B,YAA6B,IAAgC;QAAhC,SAAI,GAAJ,IAAI,CAA4B;IAAG,CAAC;IAEjE;;;;OAIG;IACH,KAAK,CAAC,gBAAgB,CAAC,IAItB;QACC,4EAA4E;QAC5E,6DAA6D;QAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;QAEtC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC3B,0EAA0E;YAC1E,qEAAqE;YACrE,+DAA+D;YAC/D,yEAAyE;YACzE,0CAA0C;YAC1C,MAAM,QAAQ,CAAC,OAAO,CACpB,gCAAgC;gBAC9B,oEAAoE;gBACpE,+DAA+D;gBAC/D,8BAA8B;gBAC9B,4DAA4D;gBAC5D,uDAAuD;gBACvD,sCAAsC;gBACtC,kDAAkD;gBAClD,4BAA4B;gBAC5B,4CAA4C;gBAC5C,0DAA0D;gBAC1D,oCAAoC;gBACpC,gCAAgC;gBAChC,qDAAqD;gBACrD,sBAAsB,EACxB;gBACE,IAAI,CAAC,QAAQ;gBACb,MAAM,CAAC,EAAE;gBACT,MAAM,CAAC,QAAQ;gBACf,MAAM,CAAC,cAAc,IAAI,IAAI;gBAC7B,MAAM,CAAC,IAAI;gBACX,MAAM,CAAC,WAAW;gBAClB,MAAM,CAAC,kBAAkB,IAAI,IAAI;gBACjC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;gBACrC,MAAM,CAAC,MAAM,IAAI,GAAG;aACrB,CACF,CAAC;QACJ,CAAC;QAED,mEAAmE;QACnE,2DAA2D;QAC3D,mDAAmD;QACnD,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,IAAI,WAAW,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,YAAY,EAAE;gBACjD,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE;aACrC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,eAAe,CAAC,IAGrB;QACC,4EAA4E;QAC5E,6DAA6D;QAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,YAAY,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACvF,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/backend/services/admin-actions-service.d.ts

@@ -0,0 +1,136 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { AdminActionView, AdminI18nTranslatePort, PermissionReadPort, SupportedAdminLanguage } from '@endora-commerce/contracts';
+export interface AdminActionsServiceDeps {
+    em: () => EntityManager;
+    /**
+     * `_i18n`'s resolver and `admin_roles`' permission read, both as the contract
+     * types those modules publish rather than their service classes (feature 075,
+     * Phase C). What this service asks for is two methods — resolve a string,
+     * list an operator's permissions — where the classes brought bundle
+     * installation, coverage snapshots and role administration across the
+     * boundary with them.
+     */
+    i18nService: AdminI18nTranslatePort;
+    permissionService: PermissionReadPort;
+    log?: {
+        info(msg: string): void;
+        warn(msg: string): void;
+    };
+    /**
+     * Feature 073 / issue #225 / issue #187 — **both** presence axes and the
+     * generation the readings came from, injected as one value.
+     *
+     * The platform axis joined this module's rows to `module_registrations` until
+     * feature 080's ledger sweep. It reads through the probe now, from the same
+     * `effectiveState` projection the operator axis has always come from, so the
+     * palette cannot disagree with the route gates about a module it advertises.
+     *
+     * Injected rather than read from the lifecycle singleton so this service
+     * stays constructible without a warmed process cache — a test that drives
+     * presence must be able to hand over the presence it is driving rather than
+     * reach for a process-wide seam.
+     *
+     * The readings and the version travel together, in one object, because a
+     * composition that supplied the first without the second would cache an
+     * answer it can never drop — and there are two composition roots to keep in
+     * step. Omitted ⇒ every module reads as present and the version never moves,
+     * which is the behaviour of an unwired composition, not a fall-open: there is
+     * no presence state to resolve at all.
+     */
+    presence?: ModulePresenceProbe;
+}
+/**
+ * Module presence, as this service consumes it: both axes and the generation
+ * the two readings came from.
+ *
+ * Both composition roots build it off `effectiveState`, which is where all
+ * three are already one object; stating them together here is what stops a
+ * root from wiring one reading without the others.
+ *
+ * The two axes stay **separate methods** rather than collapsing into
+ * `effectiveState.isPresent`, and the reason is the tri-state the combiner
+ * itself keeps: a module the deployment does not ship and a module the operator
+ * switched off are one answer to the palette and two different sentences on
+ * `/platform/modules`, so a probe that could only say "absent" would be a
+ * narrower value than the object both roots already hold. The conjunction is
+ * applied here, at the row filter, and nowhere else.
+ */
+export interface ModulePresenceProbe {
+    /**
+     * Is this module installed and enabled on this deployment?
+     *
+     * The composition roots answer it `false` for a module id the registry and
+     * the manifests both know nothing about, which is what keeps an orphan
+     * `module_actions` row — a module uninstalled without its rows being reaped —
+     * out of the palette. That used to fall out of the `module_registrations`
+     * join having no row to match.
+     */
+    isPlatformAvailable(moduleId: string): boolean;
+    /** Is this module activated by the operator? */
+    isActivated(moduleId: string): boolean;
+    /**
+     * Generation of the presence the two readings above answer from. Changes when
+     * a refresh installs presence that differs from the presence before it.
+     */
+    version(): number;
+}
+export interface ListVisibleResult {
+    actions: AdminActionView[];
+    registryVersion: number;
+}
+/**
+ * Namespace this module's palette snapshot is registered under.
+ *
+ * Deliberately **not** in `CACHE_NAMESPACES` (the `settings` module's operator
+ * "clear cache" surface): this layer owns no Redis keys, and the palette is
+ * rebuilt from PostgreSQL on the next read anyway. The registration exists for
+ * the module-state notification alone.
+ */
+export declare const ADMIN_ACTIONS_CACHE_NAMESPACE = "admin_actions";
+export declare class AdminActionsService {
+    private readonly em;
+    private readonly i18nService;
+    private readonly permissionService;
+    private readonly presence;
+    private readonly cache;
+    /** Presence generation every snapshot currently in {@link cache} was built under. */
+    private cachedPresenceVersion;
+    /** Counts service work so tests can assert cache hits / misses. */
+    stats: {
+        dbHits: number;
+        cacheHits: number;
+        invalidations: number;
+    };
+    private readonly unregisterCacheLayer;
+    constructor(deps: AdminActionsServiceDeps);
+    /**
+     * Withdraw this service's cache layer from the process registry. Production
+     * holds it until process exit; a test that builds a service per case releases
+     * it so the registry names a live cache rather than a discarded one.
+     */
+    dispose(): void;
+    /**
+     * Drop every cached snapshot. Called by the registered cache layer above and
+     * by the presence-version comparison in {@link listVisibleForOperator}.
+     */
+    invalidate(): void;
+    /**
+     * List the actions an operator may see in the command palette.
+     *
+     * Permissions are loaded via the admin_roles `PermissionService`. The
+     * action filter is the same as the existing `hasPermission()` check:
+     * `*` in the operator's role grants everything; otherwise the action's
+     * `requiredPermission` (if any) must be present in the role's array.
+     */
+    listVisibleForOperator(args: {
+        language: SupportedAdminLanguage;
+        adminUserId: string;
+    }): Promise<ListVisibleResult>;
+}
+/**
+ * Stable hash of an operator's permission set. Sorting first makes the
+ * fingerprint independent of insertion order; sha1 keeps the cache key
+ * compact while making collisions astronomically unlikely.
+ */
+export declare function fingerprintPermissions(permissions: readonly string[]): string;
+//# sourceMappingURL=admin-actions-service.d.ts.map

package/dist/backend/services/admin-actions-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actions-service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/admin-actions-service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EAEtB,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,4BAA4B,CAAC;AAuEpC,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,aAAa,CAAC;IACxB;;;;;;;OAOG;IACH,WAAW,EAAE,sBAAsB,CAAC;IACpC,iBAAiB,EAAE,kBAAkB,CAAC;IACtC,GAAG,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,gDAAgD;IAChD,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACvC;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,kBAAkB,CAAC;AAE7D,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAsB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,qFAAqF;IACrF,OAAO,CAAC,qBAAqB,CAAS;IACtC,mEAAmE;IAC5D,KAAK;;;;MAAiD;IAC7D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAa;gBAEtC,IAAI,EAAE,uBAAuB;IA8BzC;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAIf;;;OAGG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;;OAOG;IACG,sBAAsB,CAAC,IAAI,EAAE;QACjC,QAAQ,EAAE,sBAAsB,CAAC;QACjC,WAAW,EAAE,MAAM,CAAC;KACrB,GAAG,OAAO,CAAC,iBAAiB,CAAC;CA+G/B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAG7E"}

package/dist/backend/services/admin-actions-service.js

@@ -0,0 +1,168 @@
+import { createHash } from 'node:crypto';
+import { inProcessCaches } from '@endora-commerce/platform/kernel';
+/**
+ * Namespace this module's palette snapshot is registered under.
+ *
+ * Deliberately **not** in `CACHE_NAMESPACES` (the `settings` module's operator
+ * "clear cache" surface): this layer owns no Redis keys, and the palette is
+ * rebuilt from PostgreSQL on the next read anyway. The registration exists for
+ * the module-state notification alone.
+ */
+export const ADMIN_ACTIONS_CACHE_NAMESPACE = 'admin_actions';
+export class AdminActionsService {
+    em;
+    i18nService;
+    permissionService;
+    presence;
+    cache = new Map();
+    /** Presence generation every snapshot currently in {@link cache} was built under. */
+    cachedPresenceVersion;
+    /** Counts service work so tests can assert cache hits / misses. */
+    stats = { dbHits: 0, cacheHits: 0, invalidations: 0 };
+    unregisterCacheLayer;
+    constructor(deps) {
+        this.em = deps.em;
+        this.i18nService = deps.i18nService;
+        this.permissionService = deps.permissionService;
+        this.presence = deps.presence ?? {
+            isPlatformAvailable: () => true,
+            isActivated: () => true,
+            version: () => 0,
+        };
+        this.cachedPresenceVersion = this.presence.version();
+        // D-174 — this process's palette snapshot, announced to the platform so its
+        // module-state subscriber can drop it. Unconditional: the registry is
+        // process-local and a drop costs a `Map.clear()`, so there is nothing for a
+        // composition to get wrong by omission. A second composition in the same
+        // process (the harness builds one per test file) replaces the entry.
+        this.unregisterCacheLayer = inProcessCaches.register(ADMIN_ACTIONS_CACHE_NAMESPACE, {
+            invalidateAll: async () => {
+                this.invalidate();
+                // No shared layer: this cache is a `Map`, so no Redis key was deleted
+                // and the operator-facing count this return value feeds is zero.
+                return 0;
+            },
+        }, { invalidateOnModuleStateChange: true });
+    }
+    /**
+     * Withdraw this service's cache layer from the process registry. Production
+     * holds it until process exit; a test that builds a service per case releases
+     * it so the registry names a live cache rather than a discarded one.
+     */
+    dispose() {
+        this.unregisterCacheLayer();
+    }
+    /**
+     * Drop every cached snapshot. Called by the registered cache layer above and
+     * by the presence-version comparison in {@link listVisibleForOperator}.
+     */
+    invalidate() {
+        this.cache.clear();
+        this.stats.invalidations += 1;
+    }
+    /**
+     * List the actions an operator may see in the command palette.
+     *
+     * Permissions are loaded via the admin_roles `PermissionService`. The
+     * action filter is the same as the existing `hasPermission()` check:
+     * `*` in the operator's role grants everything; otherwise the action's
+     * `requiredPermission` (if any) must be present in the role's array.
+     */
+    async listVisibleForOperator(args) {
+        // Issue #225 — before anything is served from the snapshot, ask whether the
+        // presence it was built from is still the presence being answered. A read
+        // that landed while `registryCache.refreshFromDb` was in flight built its
+        // snapshot from the pre-refresh maps; the version moves when that refresh
+        // lands, and this is where the snapshot goes with it. The number is recorded
+        // *before* the rebuild below, so a refresh completing while that rebuild is
+        // running is caught by the next read rather than becoming permanent.
+        const presenceVersion = this.presence.version();
+        if (presenceVersion !== this.cachedPresenceVersion) {
+            this.cachedPresenceVersion = presenceVersion;
+            this.invalidate();
+        }
+        const permissions = await this.permissionService.listPermissions(args.adminUserId);
+        const fingerprint = fingerprintPermissions(permissions);
+        const cacheKey = `${args.language}::${fingerprint}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            this.stats.cacheHits += 1;
+            return cached;
+        }
+        this.stats.dbHits += 1;
+        const knex = this.em().getKnex();
+        // This module's own table and nothing else. Presence is decided below,
+        // against the probe, for both axes at once.
+        const rows = (await knex('module_actions as a')
+            .select('a.module_id', 'a.action_id', 'a.label_key', 'a.description_key', 'a.icon', 'a.target_route', 'a.required_permission', 'a.keywords', 'a.weight', 'a.version'));
+        const visible = [];
+        for (const row of rows) {
+            // Constitution XVII — effective presence is the conjunction of the two
+            // axes, and both are asked here so neither can be forgotten by one of
+            // them moving. A palette that advertises an absent module's action leads
+            // an operator straight to a 503, which is the same defect as an
+            // unfiltered sidebar; one that hides a present module's action is the
+            // same defect wearing the other sign.
+            if (!this.presence.isPlatformAvailable(row.module_id))
+                continue;
+            if (!this.presence.isActivated(row.module_id))
+                continue;
+            if (row.required_permission == null ||
+                permissions.includes('*') ||
+                permissions.includes(row.required_permission)) {
+                visible.push(row);
+            }
+        }
+        let registryVersion = 0;
+        const collator = new Intl.Collator(args.language, {
+            sensitivity: 'base',
+            numeric: true,
+        });
+        const resolved = [];
+        for (const row of visible) {
+            const v = Number(row.version);
+            if (v > registryVersion)
+                registryVersion = v;
+            const label = await this.i18nService.translate(row.module_id, row.label_key, args.language);
+            let description = null;
+            if (row.description_key) {
+                const resolvedDescription = await this.i18nService.translate(row.module_id, row.description_key, args.language);
+                // The resolver returns `${moduleId}.${key}` as a placeholder when
+                // the key is missing — surface that as `null` rather than a
+                // raw-key string in the description slot.
+                description =
+                    resolvedDescription === `${row.module_id}.${row.description_key}`
+                        ? null
+                        : resolvedDescription;
+            }
+            resolved.push({
+                moduleId: row.module_id,
+                actionId: row.action_id,
+                label,
+                description,
+                icon: row.icon,
+                targetRoute: row.target_route,
+                keywords: Array.isArray(row.keywords) ? row.keywords : [],
+                weight: row.weight,
+            });
+        }
+        resolved.sort((a, b) => {
+            if (a.weight !== b.weight)
+                return a.weight - b.weight;
+            return collator.compare(a.label, b.label);
+        });
+        const result = { actions: resolved, registryVersion };
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+}
+/**
+ * Stable hash of an operator's permission set. Sorting first makes the
+ * fingerprint independent of insertion order; sha1 keeps the cache key
+ * compact while making collisions astronomically unlikely.
+ */
+export function fingerprintPermissions(permissions) {
+    const sorted = [...permissions].sort();
+    return createHash('sha1').update(sorted.join('\0')).digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=admin-actions-service.js.map

package/dist/backend/services/admin-actions-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-actions-service.js","sourceRoot":"","sources":["../../../src/backend/services/admin-actions-service.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,196 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import { type ModuleLifecycleParticipant } from '@endora-commerce/contracts';
+/**
+ * Admin Command Palette Actions Registry — feature 020.
+ *
+ * Owns the `module_actions` table, the install-time reconciler that
+ * ingests every module's manifest `actions` array, the in-process
+ * cache, and the read API consumed by the admin SPA's command palette.
+ * Itself declares no actions — this module is platform plumbing, not
+ * a place to surface UI features.
+ *
+ * Depends on `_lifecycle` because every module's action install / hard-
+ * uninstall is driven by the lifecycle orchestrator's hook surface, and
+ * on `_i18n` because action labels and descriptions are resolved
+ * through the existing translation-bundle resolver.
+ */
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "uuid" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+/**
+ * `module_actions` follows the manifest set — feature 080, T036a / D-159.
+ *
+ * `_i18n/manifest.ts` states the shape's reasoning in full; this module is the
+ * second instance of it, projecting every other module's `manifest.actions`
+ * array instead of its `i18n` block.
+ *
+ * **It is not gated on this module's own activation, and that is a ruling**
+ * (D-159 §9, the owner, 2026-08-22). `composition.ts` used to forward the
+ * reconciler as a lazily-resolved port, so an operator who had switched the
+ * command palette off could not install an *unrelated* module — the install
+ * aborted on a `MODULE_DISABLED` from a discovery surface that has nothing to
+ * do with it. That was the better of the only two options then on the table,
+ * the other being a backend that would not start; the third, which this takes,
+ * is that a projection of manifest data is written whether or not anything is
+ * serving it. The rows are inert while the palette is off and the palette
+ * answers from them, unchanged, the moment it is switched back on.
+ */
+export declare const lifecycleParticipant: ModuleLifecycleParticipant<EntityManager>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAwB,KAAK,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAEnG;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmCnB,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,EAAE,0BAA0B,CAAC,aAAa,CAoB1E,CAAC"}