Roles and Capabilities API

$ wp eval 'foreach ( array( 5, 6, 7 ) as $id ) { echo $id, ": ", implode( ", ", map_meta_cap( "edit_lp_book", 3, $id ) ), "\n"; }'
5: edit_others_lp_books, edit_published_lp_books
6: edit_lp_books
7: edit_lp_books, edit_others_lp_books

<?php
/**
 * Runtime capability rules for books.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Filters that refine what the stored capabilities allow.
 */
final class Capabilities {

	public static function register(): void {
		add_filter( 'map_meta_cap', array( self::class, 'lock_submitted_books' ), 10, 4 );
		add_filter( 'user_has_cap', array( self::class, 'freeze_catalogue' ), 10, 4 );
	}

	/**
	 * Authors edit only their own books, and only until they submit them for review.
	 *
	 * @param string[] $caps    Primitive capabilities core requires.
	 * @param string   $cap     Capability checked: edit_post, not edit_lp_book (see below).
	 * @param int      $user_id User being checked.
	 * @param array    $args    Context; $args[0] is the post ID.
	 */
	public static function lock_submitted_books( $caps, $cap, $user_id, $args ) {
		if ( ! in_array( $cap, array( 'edit_post', 'delete_post' ), true ) || empty( $args[0] ) ) {
			return $caps;
		}

		$post = get_post( (int) $args[0] );
		if ( ! $post || 'lp_book' !== $post->post_type || 'pending' !== $post->post_status ) {
			return $caps;
		}

		// Core asked for edit_lp_books (own pending book); require the reviewer's capability instead.
		if ( (int) $post->post_author === (int) $user_id ) {
			$caps[] = 'edit_others_lp_books';
		}

		return $caps;
	}

	/**
	 * While the catalogue is frozen for stock-taking, only administrators change books.
	 *
	 * @param bool[]   $allcaps Capabilities the user has (role and user grants combined).
	 * @param string[] $caps    Primitive capabilities being checked.
	 * @param array    $args    Requested capability, user ID, then context.
	 * @param \WP_User $user    The user.
	 */
	public static function freeze_catalogue( $allcaps, $caps, $args, $user ) {
		$settings = (array) get_option( 'lp_catalog_settings', array() );
		if ( empty( $settings['catalogue_frozen'] ) || ! empty( $allcaps['manage_options'] ) ) {
			return $allcaps;
		}

		foreach ( Roles::book_caps() as $book_cap ) {
			if ( 'manage_lp_terms' !== $book_cap ) {
				$allcaps[ $book_cap ] = false;
			}
		}

		return $allcaps;
	}
}

<?php
// wp eval-file matrix.php: one row per check, one column per user.
$logins = array( 'admin', 'maria.editor', 'tom.author', 'lena.catalogue', 'sam.reader' );
$checks = array( array( 'edit_lp_books' ), array( 'publish_lp_books' ), array( 'edit_lp_book', 5 ), array( 'edit_lp_book', 6 ),
	array( 'edit_lp_book', 7 ), array( 'delete_lp_book', 6 ), array( 'manage_lp_terms' ), array( 'edit_posts' ) );

vprintf( '%-20s' . str_repeat( '%-16s', 5 ) . "\n", array_merge( array( 'capability' ), $logins ) );
foreach ( $checks as $check ) {
	printf( '%-20s', implode( ' ', $check ) );
	foreach ( $logins as $login ) {
		printf( '%-16s', user_can( get_user_by( 'login', $login ), ...$check ) ? 'yes' : 'no' );
	}
	echo "\n";
}

capability          admin           maria.editor    tom.author      lena.catalogue  sam.reader
edit_lp_books       yes             yes             yes             yes             no
publish_lp_books    yes             yes             no              yes             no
edit_lp_book 5      yes             yes             no              yes             no
edit_lp_book 6      yes             yes             yes             yes             no
edit_lp_book 7      yes             yes             no              yes             no
delete_lp_book 6    yes             yes             yes             yes             no
manage_lp_terms     yes             yes             no              yes             no
edit_posts          yes             yes             yes             no              no

<?php
/**
 * REST route lumen/v1/books/<id>/stock.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Lets people who may edit a book correct its stock count.
 */
final class StockController {

	public static function register_routes(): void {
		register_rest_route(
			'lumen/v1',
			'/books/(?P<id>\d+)/stock',
			array(
				'methods'             => 'PUT',
				'callback'            => array( self::class, 'update' ),
				'permission_callback' => array( self::class, 'can_update' ),
				'args'                => array(
					'id'       => array( 'type' => 'integer', 'required' => true ),
					'quantity' => array( 'type' => 'integer', 'minimum' => 0, 'required' => true ),
				),
			)
		);
	}

	/**
	 * The meta capability, checked against this book: ownership, status and filters all apply.
	 *
	 * @param \WP_REST_Request $request Request.
	 * @return true|\WP_Error
	 */
	public static function can_update( \WP_REST_Request $request ) {
		$book = get_post( (int) $request['id'] );
		if ( ! $book || 'lp_book' !== $book->post_type ) {
			return new \WP_Error( 'lp_book_not_found', __( 'No such book.', 'lumen-catalog' ), array( 'status' => 404 ) );
		}
		if ( ! current_user_can( 'edit_lp_book', $book->ID ) ) {
			return new \WP_Error(
				'lp_cannot_update_stock',
				__( 'Sorry, you are not allowed to change the stock of this book.', 'lumen-catalog' ),
				array( 'status' => rest_authorization_required_code() )
			);
		}
		return true;
	}

	/**
	 * Stores the new quantity in the lp_stock post meta and records the change in the stock history.
	 *
	 * @param \WP_REST_Request $request Request.
	 */
	public static function update( \WP_REST_Request $request ) {
		global $wpdb;
		$book_id  = (int) $request['id'];
		$quantity = (int) $request['quantity'];
		$previous = (int) get_post_meta( $book_id, 'lp_stock', true );

		update_post_meta( $book_id, 'lp_stock', $quantity );
		$row = array( 'book_id' => $book_id, 'delta' => $quantity - $previous, 'quantity' => $quantity, 'changed_at' => current_time( 'mysql', true ) );
		$wpdb->insert( $wpdb->prefix . 'lp_stock', $row, array( '%d', '%d', '%d', '%s' ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery
		return rest_ensure_response( array( 'book' => $book_id, 'quantity' => $quantity ) );
	}
}

user            method route                            status code or result
maria.editor    POST   /wp/v2/lp_book (draft)            201    id=8 status=draft
tom.author      POST   /wp/v2/lp_book (draft)            201    id=9 status=draft
lena.catalogue  POST   /wp/v2/lp_book (draft)            201    id=10 status=draft
sam.reader      POST   /wp/v2/lp_book (draft)            403    rest_cannot_create
tom.author      POST   /wp/v2/lp_book (publish)          403    rest_cannot_publish
tom.author      POST   /wp/v2/lp_book/5                  403    rest_cannot_edit
lena.catalogue  POST   /wp/v2/lp_book/5                  200    id=5 status=publish
tom.author      POST   /wp/v2/lp_book/6                  200    id=6 status=draft
tom.author      POST   /wp/v2/lp_book/7                  403    rest_cannot_edit
lena.catalogue  POST   /wp/v2/posts (draft)              403    rest_cannot_create
tom.author      PUT    /lumen/v1/books/5/stock           403    lp_cannot_update_stock
lena.catalogue  PUT    /lumen/v1/books/5/stock           200    {"book":5,"quantity":40}

$ wp role exists lp_catalogue_manager --url=http://lumenpress.test
Success: Role with ID 'lp_catalogue_manager' exists.
$ wp role exists lp_catalogue_manager --url=http://lumenpress.test/kids
Error: Role with ID 'lp_catalogue_manager' does not exist.
$ wp role exists lp_catalogue_manager --url=http://lumenpress.test/noir
Success: Role with ID 'lp_catalogue_manager' exists.

$ wp super-admin add maria.editor
Success: Granted super-admin capabilities to 1 user.
$ wp eval '$maria = get_user_by( "login", "maria.editor" ); foreach ( array( array( "edit_lp_book", 7 ), array( "edit_lp_book", 999 ), array( "manage_network_plugins" ), array( "lumen_anything" ) ) as $c ) { printf( "%-26s %s\n", implode( " ", $c ), user_can( $maria, ...$c ) ? "yes" : "no" ); }'
edit_lp_book 7             yes
edit_lp_book 999           no
manage_network_plugins     yes
lumen_anything             yes