@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

package/resources/claude-customizations/.claude/lib/bash/mutate-parallel-run.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# mutate-parallel-run.sh: destination-portable command-line entry point for the
+# decision and audit-record steps of the parallel-add, parallel-close, and
+# parallel-orchestrate skills (issue #890). It exists so a workspace that
+# received the Claude customization payload can run those steps with nothing
+# but bash -- no interpreter, no repository checkout.
+#
+# Usage:
+#   bash .claude/lib/bash/mutate-parallel-run.sh admit --candidate <key> \
+#       [--edges "<a>:<b> ..."] --in-flight "<k> ..." \
+#       --current-cohort-members "<k> ..."
+#   bash .claude/lib/bash/mutate-parallel-run.sh recolor --unstarted "<k> ..." \
+#       [--edges "<a>:<b> ..."] --pinned "<k> ..." --generation <g> \
+#       --current-cohort <c> --highest-pinned-cohort <h>
+#   bash .claude/lib/bash/mutate-parallel-run.sh add-entry --item <key> \
+#       --deferred true|false --generation <g> [--at <timestamp>]
+#   bash .claude/lib/bash/mutate-parallel-run.sh close --items "<k>:<state> ..."
+#   bash .claude/lib/bash/mutate-parallel-run.sh close-entry --generation <g> \
+#       [--at <timestamp>]
+#   bash .claude/lib/bash/mutate-parallel-run.sh requeue-entry --item <key> \
+#       --generation <g> [--at <timestamp>]
+#
+# `--edges` is optional; `--in-flight`, `--current-cohort-members`,
+# `--unstarted`, `--pinned`, and `--items` accept an empty string. Integer
+# tokens match `-?(0|[1-9][0-9]*)`. An `--items` token is an integer, a colon,
+# and a `[A-Za-z_]+` state; a duplicate key is a usage error. `--at` defaults to
+# the current UTC time as yyyy-MM-ddTHH-mm; the clock is read only when `--at`
+# is omitted.
+#
+# Exit-code contract (identical to remove-parallel-item.sh):
+#   exit 0  success; one compact JSON object on stdout
+#   exit 1  rule rejection; the reference implementation's exact message as
+#           one stderr line
+#   exit 2  usage error; one stderr line beginning
+#           "PARALLEL_MUTATION_ERROR: usage error:"
+# Argument validation runs first, then rule rejection, then output.
+#
+# Parity reference: scripts/dev_tools/parallel_mutation_protocol.py
+# (decide_admission, recolor_unstarted, decide_close) and
+# scripts/dev_tools/_parallel_mutation_entries.py (build_add_entry,
+# build_close_entry, build_requeue_entry).
+#
+# Declared divergences (also listed in both parity lanes):
+#   1. A duplicate key in `close --items` is a usage error (exit 2); the Python
+#      mapping would silently keep the last record for that key.
+#   2. `at` is a caller-supplied string instead of a `datetime`.
+#   3. Option abbreviations are rejected.
+#   4. `admit` has no rejection branch, in either implementation.
+set -euo pipefail
+
+# Resolve this script's own directory so the libraries source regardless of cwd.
+MPR_SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-mutation-ops.sh
+# shellcheck disable=SC1091
+source "$MPR_SCRIPT_DIR/parallel-mutation-ops.sh"
+# shellcheck source=.claude/lib/bash/parallel-mutation-cli.sh
+# shellcheck disable=SC1091
+source "$MPR_SCRIPT_DIR/parallel-mutation-cli.sh"
+
+pc_enforce_c_locale
+
+mpr_admit() {
+	# Run the admit subcommand.
+	local candidate edges in_flight members rc=0
+	pmcli_parse_options "candidate edges in-flight current-cohort-members" "$@"
+	pmcli_require candidate in-flight current-cohort-members
+	pmcli_integer "${PMCLI_OPTS[candidate]}" "--candidate"
+	candidate="$PMCLI_VALUE"
+	pmcli_edge_list "${PMCLI_OPTS[edges]-}"
+	edges="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS["in-flight"]}" "--in-flight"
+	in_flight="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS["current-cohort-members"]}" "--current-cohort-members"
+	members="$PMCLI_VALUE"
+	pm_decide_admission "$candidate" "$edges" "$in_flight" "$members" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_recolor() {
+	# Run the recolor subcommand; same options as remove-parallel-item.sh.
+	local unstarted edges pinned generation current highest rc=0
+	pmcli_parse_options "unstarted edges pinned generation current-cohort highest-pinned-cohort" "$@"
+	pmcli_require unstarted pinned generation current-cohort highest-pinned-cohort
+	pmcli_integer_list "${PMCLI_OPTS[unstarted]}" "--unstarted"
+	unstarted="$PMCLI_VALUE"
+	pmcli_edge_list "${PMCLI_OPTS[edges]-}"
+	edges="$PMCLI_VALUE"
+	pmcli_integer_list "${PMCLI_OPTS[pinned]}" "--pinned"
+	pinned="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS["current-cohort"]}" "--current-cohort"
+	current="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS["highest-pinned-cohort"]}" "--highest-pinned-cohort"
+	highest="$PMCLI_VALUE"
+	pm_recolor_unstarted "$unstarted" "$edges" "$pinned" "$generation" "$current" "$highest" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_add_entry() {
+	# Run the add-entry subcommand.
+	local item deferred generation at rc=0
+	pmcli_parse_options "item deferred generation at" "$@"
+	pmcli_require item deferred generation
+	pmcli_integer "${PMCLI_OPTS[item]}" "--item"
+	item="$PMCLI_VALUE"
+	deferred="${PMCLI_OPTS[deferred]}"
+	[[ $deferred == true || $deferred == false ]] ||
+		pmcli_usage_error "--deferred must be true or false; found: $deferred"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_add_entry "$item" "$deferred" "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_close() {
+	# Run the close subcommand over every `<key>:<state>` token.
+	local token key state canonical="" seen=" " rc=0
+	pmcli_parse_options "items" "$@"
+	pmcli_require items
+	pcoh_split_words "${PMCLI_OPTS[items]}"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		[[ $token =~ ^(-?(0|[1-9][0-9]*)):([A-Za-z_]+)$ ]] ||
+			pmcli_usage_error "--items token must be <key>:<state>; found: $token"
+		state="${BASH_REMATCH[3]}"
+		key=$((BASH_REMATCH[1]))
+		# A duplicate key would let one record silently replace another, so it
+		# is rejected before the library runs (declared divergence 1).
+		[[ $seen != *" $key "* ]] || pmcli_usage_error "--items key given more than once: $key"
+		seen="$seen$key "
+		canonical="$canonical $key:$state"
+	done
+	pm_decide_close "${canonical# }" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_close_entry() {
+	# Run the close-entry subcommand.
+	local generation at rc=0
+	pmcli_parse_options "generation at" "$@"
+	pmcli_require generation
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_close_entry "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_requeue_entry() {
+	# Run the requeue-entry subcommand.
+	local item generation at rc=0
+	pmcli_parse_options "item generation at" "$@"
+	pmcli_require item generation
+	pmcli_integer "${PMCLI_OPTS[item]}" "--item"
+	item="$PMCLI_VALUE"
+	pmcli_integer "${PMCLI_OPTS[generation]}" "--generation"
+	generation="$PMCLI_VALUE"
+	pmcli_timestamp
+	at="$PMCLI_VALUE"
+	pm_build_requeue_entry "$item" "$generation" "$at" || rc=$?
+	pmcli_emit "$rc"
+}
+
+mpr_main() {
+	# Dispatch on the subcommand.
+	(($# > 0)) ||
+		pmcli_usage_error "missing subcommand; expected one of admit, recolor, add-entry, close, close-entry, requeue-entry"
+	local subcommand="$1"
+	shift
+	case "$subcommand" in
+	admit) mpr_admit "$@" ;;
+	recolor) mpr_recolor "$@" ;;
+	add-entry) mpr_add_entry "$@" ;;
+	close) mpr_close "$@" ;;
+	close-entry) mpr_close_entry "$@" ;;
+	requeue-entry) mpr_requeue_entry "$@" ;;
+	*) pmcli_usage_error "unknown subcommand: $subcommand" ;;
+	esac
+}
+
+# Guard so the file can be sourced without executing main. main's return code
+# is captured and re-exited explicitly as the final statement.
+if [[ ${BASH_SOURCE[0]} == "${0}" ]]; then
+	mpr_rc=0
+	mpr_main "$@" || mpr_rc=$?
+	exit "$mpr_rc"
+fi

package/resources/claude-customizations/.claude/lib/bash/parallel-cohorts.sh

@@ -52,14 +52,19 @@ PCOH_RESULT=""
 PCOH_WORDS=()
 
 pcoh_split_words() {
-	# Populate PCOH_WORDS by splitting a space-separated string.
+	# Populate PCOH_WORDS by splitting a whitespace-separated string.
 	#
 	# Args: $1 = the string to split. An empty or whitespace-only string yields
 	# an empty array, which is the empty-graph and empty-cohort case. `read -ra`
 	# is used rather than an unquoted expansion so a token is never subjected to
-	# pathname expansion.
+	# pathname expansion. Newline, CR, VT, and FF are converted to spaces first:
+	# `read` consumes one newline-terminated record and splits it on IFS only, so
+	# without the conversion every token after the first newline is dropped and
+	# CR, VT, and FF are not separators. With it, the separator set is space, tab,
+	# LF, CR, VT, and FF, which matches Python str.split() for ASCII.
+	local text="${1-}"
 	PCOH_WORDS=()
-	read -ra PCOH_WORDS <<<"${1-}"
+	read -ra PCOH_WORDS <<<"${text//[$'\n\r\v\f']/ }"
 }
 
 pcoh_fail() {
@@ -123,9 +128,14 @@ pcoh_build_adjacency() {
 	PCOH_ADJACENT=()
 	pcoh_split_words "$keys"
 	local -a key_list=("${PCOH_WORDS[@]}")
+	# Rebuild the membership haystack from the split tokens. The endpoint checks
+	# below match a space-delimited word, so they would miss a key that the caller
+	# separated with a newline, tab, CR, VT, or FF instead of a single space.
+	keys=""
 	# Seed every declared key so an isolated vertex survives into the coloring
 	# step; inferring vertices from the edge list alone would drop it.
 	for key in "${key_list[@]}"; do
+		keys="$keys $key"
 		PCOH_DEGREE["$key"]=0
 		PCOH_NEIGHBORS["$key"]=""
 	done

package/resources/claude-customizations/.claude/lib/bash/parallel-mutation-cli.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# parallel-mutation-cli.sh: sourceable command-line helpers shared by the two
+# parallel mutation entry points, remove-parallel-item.sh (issue #791) and
+# mutate-parallel-run.sh (issue #890). It holds option parsing, required-option
+# checks, integer, key-list, and edge-list validation, the `--at` timestamp, and
+# the result printer, so both entry points apply one grammar and one exit-code
+# contract.
+#
+# Grammar. Every option takes exactly one value. An unknown name, an
+# abbreviation, a `--name=value` form, a repeated option, or a missing value is
+# a usage error; a value beginning with `--` counts as missing. Integer tokens
+# match `-?(0|[1-9][0-9]*)`. `--at` matches `[0-9A-Za-z:.+-]+` and defaults to
+# the current UTC minute as yyyy-MM-ddTHH-mm.
+#
+# Exit-code contract carried by these helpers:
+#   exit 2  usage error; one stderr line beginning
+#           "PARALLEL_MUTATION_ERROR: usage error:" (pmcli_usage_error)
+#   exit 1  rule rejection; PM_ERROR printed as one stderr line (pmcli_emit)
+#   exit 0  success; PM_RESULT printed as one stdout line (pmcli_emit)
+#
+# Dependencies. pmcli_emit reads PM_RESULT and PM_ERROR, which
+# parallel-mutation.sh owns; an entry point sources that library before calling
+# it. The only external command is `date`, run solely when `--at` is omitted.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because PMCLI_OPTS and PMCLI_VALUE are written
+# here and read by the two entry points, which shellcheck analyses separately.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PMCLI_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-cohorts.sh
+# shellcheck disable=SC1091
+source "$PMCLI_LIB_DIR/parallel-cohorts.sh"
+
+# Parsed option values, keyed by option name without the leading dashes.
+declare -gA PMCLI_OPTS=()
+
+# The canonical value stored by the most recent validator.
+PMCLI_VALUE=""
+
+pmcli_usage_error() {
+	# Print one usage-error line on stderr and exit 2.
+	#
+	# Args: $1 = the specific reason.
+	printf 'PARALLEL_MUTATION_ERROR: usage error: %s\n' "$1" >&2
+	exit 2
+}
+
+pmcli_parse_options() {
+	# Parse `--name value` pairs into PMCLI_OPTS against an allowed-name list.
+	#
+	# Args: $1 = space-separated allowed option names, then the arguments.
+	local allowed="$1" name
+	shift
+	PMCLI_OPTS=()
+	while (($# > 0)); do
+		name="${1#--}"
+		if [[ $1 != --* ]] || ! pc_contains_word "$allowed" "$name"; then
+			pmcli_usage_error "unknown option: $1"
+		fi
+		if [[ -n ${PMCLI_OPTS["$name"]+set} ]]; then
+			pmcli_usage_error "option given more than once: $1"
+		fi
+		if (($# < 2)) || [[ $2 == --* ]]; then
+			pmcli_usage_error "option $1 requires a value"
+		fi
+		PMCLI_OPTS["$name"]="$2"
+		shift 2
+	done
+}
+
+pmcli_require() {
+	# Exit with a usage error unless every named option was supplied.
+	#
+	# Args: the option names that are required.
+	local name
+	for name in "$@"; do
+		[[ -n ${PMCLI_OPTS["$name"]+set} ]] || pmcli_usage_error "missing required option: --$name"
+	done
+}
+
+pmcli_integer() {
+	# Validate one integer token and store it in canonical form in PMCLI_VALUE.
+	#
+	# Args: $1 = the token, $2 = a label naming where it came from. The
+	# validators store their result in a global instead of echoing it, because
+	# a usage error raised inside a command substitution would exit only the
+	# subshell.
+	if [[ ! $1 =~ ^-?(0|[1-9][0-9]*)$ ]]; then
+		pmcli_usage_error "$2 must be a decimal integer matching -?(0|[1-9][0-9]*); found: $1"
+	fi
+	PMCLI_VALUE=$(($1))
+}
+
+pmcli_integer_list() {
+	# Validate a whitespace-separated key list; store it space separated.
+	#
+	# Args: $1 = the list, $2 = a label naming the option.
+	local token canonical=""
+	pcoh_split_words "$1"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		pmcli_integer "$token" "$2 key"
+		canonical="$canonical $PMCLI_VALUE"
+	done
+	PMCLI_VALUE="${canonical# }"
+}
+
+pmcli_edge_list() {
+	# Validate a whitespace-separated `a:b` edge list; store it canonical.
+	#
+	# Args: $1 = the edge list.
+	local token first canonical=""
+	pcoh_split_words "$1"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		if [[ $token != *:* || $token == *:*:* ]]; then
+			pmcli_usage_error "edge must be <a>:<b>; found: $token"
+		fi
+		pmcli_integer "${token%%:*}" "edge endpoint"
+		first="$PMCLI_VALUE"
+		pmcli_integer "${token#*:}" "edge endpoint"
+		canonical="$canonical $first:$PMCLI_VALUE"
+	done
+	PMCLI_VALUE="${canonical# }"
+}
+
+pmcli_timestamp() {
+	# Store the validated `--at` value, or the current UTC minute when omitted.
+	if [[ -n ${PMCLI_OPTS[at]+set} ]]; then
+		PMCLI_VALUE="${PMCLI_OPTS[at]}"
+		[[ $PMCLI_VALUE =~ ^[0-9A-Za-z:.+-]+$ ]] ||
+			pmcli_usage_error "--at must match [0-9A-Za-z:.+-]+; found: $PMCLI_VALUE"
+	else
+		# The only clock read of either entry point, taken only when --at is
+		# omitted.
+		PMCLI_VALUE=$(date -u +%Y-%m-%dT%H-%M)
+	fi
+}
+
+pmcli_emit() {
+	# Print the library outcome and return the matching exit code.
+	#
+	# Args: $1 = the library function's return code.
+	if (($1 != 0)); then
+		printf '%s\n' "$PM_ERROR" >&2
+		return 1
+	fi
+	printf '%s\n' "$PM_RESULT"
+	return 0
+}

package/resources/claude-customizations/.claude/lib/bash/parallel-mutation-ops.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# parallel-mutation-ops.sh: sourceable bash port of the add, close, and requeue
+# functions of the parallel mutation engine (issue #890), so a workspace that
+# received the Claude customization payload can decide an admission, gate a run
+# close, and build the add, close, and requeue mutations[] records without an
+# interpreter. It sources parallel-mutation.sh, which carries the removal
+# functions and the shared message builders.
+#
+# Parity reference (the repository authority; this file reproduces its
+# observable outputs and rejection messages byte for byte):
+#   decide_admission     scripts/dev_tools/parallel_mutation_protocol.py
+#   decide_close         scripts/dev_tools/parallel_mutation_protocol.py
+#   build_add_entry      scripts/dev_tools/_parallel_mutation_entries.py
+#   build_close_entry    scripts/dev_tools/_parallel_mutation_entries.py
+#   build_requeue_entry  scripts/dev_tools/_parallel_mutation_entries.py
+#   ItemRecord, MutationEntry  scripts/dev_tools/_parallel_mutation_models.py
+#   rejection messages   scripts/dev_tools/_parallel_mutation_errors.py
+#
+# Declared divergences (also listed in both parity lanes):
+#   1. A duplicate key in `close --items` is a usage error (exit 2) raised by
+#      the command line; the Python mapping would keep the last record.
+#   2. `at` is a caller-supplied string instead of a `datetime`.
+#   3. Option abbreviations are rejected.
+#   4. `admit` has no rejection branch, in either implementation.
+#
+# Contract. Every public function is pure: no file I/O, no network access, no
+# clock read, and no external utility beyond `sort`. Each sets PM_RESULT to one
+# compact JSON object and returns 0 on success, or sets PM_ERROR to the exact
+# reference message and returns 1 on a rule rejection. Integer arguments are
+# expected in canonical decimal form; the entry point mutate-parallel-run.sh
+# validates them before calling here. Entry validation order follows
+# MutationEntry: the stamped recolor_generation first, then item_key.
+#
+# shellcheck disable=SC2034
+# SC2034 is disabled file-wide because PM_RESULT and PM_ERROR are written here
+# and read by the entry point mutate-parallel-run.sh and by the bats suites,
+# which shellcheck analyses separately.
+
+# Resolve this file's own directory so its dependencies source regardless of
+# the caller's working directory.
+PMOPS_LIB_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=.claude/lib/bash/parallel-mutation.sh
+# shellcheck disable=SC1091
+source "$PMOPS_LIB_DIR/parallel-mutation.sh"
+
+pm_decide_admission() {
+	# Decide whether a candidate joins the current cohort or is deferred.
+	#
+	# Args: $1 = candidate key, $2 = space-separated `a:b` conflict edges over
+	# all items, $3 = space-separated in-flight keys, $4 = space-separated
+	# current-cohort member keys. The candidate is deferred when any edge joins
+	# it to a key in the union of $3 and $4, in either endpoint position.
+	# Returns 0 with PM_RESULT holding the decision; admission never rejects.
+	local candidate="$1" edges="$2" edge first second outcome="admit_current_cohort"
+	local recompute=false
+	PM_RESULT=""
+	PM_ERROR=""
+	pcoh_split_words "$3 $4"
+	local blocking=" ${PCOH_WORDS[*]} "
+	pcoh_split_words "$edges"
+	local -a edge_list=("${PCOH_WORDS[@]}")
+	# Scan every edge for one joining the candidate to a blocking key; the
+	# first such edge settles the decision.
+	for edge in "${edge_list[@]}"; do
+		first="${edge%%:*}"
+		second="${edge#*:}"
+		if { [[ $first == "$candidate" ]] && [[ $blocking == *" $second "* ]]; } ||
+			{ [[ $second == "$candidate" ]] && [[ $blocking == *" $first "* ]]; }; then
+			outcome="defer_and_recolor"
+			recompute=true
+			break
+		fi
+	done
+	PM_RESULT="{\"candidate\":$candidate,\"outcome\":\"$outcome\",\"triggers_recompute\":$recompute}"
+	return 0
+}
+
+pm_build_add_entry() {
+	# Build the single mutations[] record for an accepted add.
+	#
+	# Args: $1 = item key, $2 = `true` for a deferred add (stamps g + 1),
+	# otherwise `false` (stamps g), $3 = the generation before the add, $4 =
+	# the `at` timestamp string. Returns 0 with PM_RESULT holding the record in
+	# F3 field order, 1 with PM_ERROR holding the reference contract message.
+	local item_key="$1" deferred="$2" generation="$3" at="$4" stamped
+	PM_RESULT=""
+	PM_ERROR=""
+	stamped="$generation"
+	if [[ $deferred == true ]]; then
+		stamped=$((generation + 1))
+	fi
+	if ((stamped < 0)); then
+		pm_fail "$(pm_entry_contract_message recolor_generation "$stamped" add)"
+		return 1
+	fi
+	if ((item_key <= 0)); then
+		pm_fail "$(pm_entry_contract_message item_key "$item_key" add)"
+		return 1
+	fi
+	PM_RESULT="{\"op\":\"add\",\"item_key\":$item_key,\"at\":$(pm_json_string "$at"),\"prior_state\":null,\"new_state\":\"scheduled\",\"disposition\":null,\"recolor_generation\":$stamped}"
+	return 0
+}
+
+pm_in_flight_list() {
+	# Echo a key list as Python renders a list of ints, ascending.
+	#
+	# Args: $1 = space-separated keys, at least one.
+	local ordered key rendered=""
+	pcoh_split_words "$1"
+	ordered=$(printf '%s\n' "${PCOH_WORDS[@]}" | LC_ALL=C sort -n)
+	while IFS= read -r key; do
+		[[ -n $key ]] || continue
+		[[ -z $rendered ]] || rendered="$rendered, "
+		rendered="$rendered$key"
+	done <<<"$ordered"
+	printf '[%s]' "$rendered"
+}
+
+pm_decide_close() {
+	# Gate a run close on no item being in flight.
+	#
+	# Args: $1 = space-separated `<key>:<state>` tokens, one per tracked item.
+	# Each token is validated in supplied order as the reference ItemRecord
+	# constructor validates it: a non-positive key names nothing the run
+	# tracks, and an out-of-enum state is rejected with the item-state members.
+	# Returns 0 with PM_RESULT `{"close_permitted":true}`, or 1 with PM_ERROR
+	# naming every in-flight key ascending.
+	local token key state in_flight=""
+	PM_RESULT=""
+	PM_ERROR=""
+	pcoh_split_words "$1"
+	local -a tokens=("${PCOH_WORDS[@]}")
+	for token in "${tokens[@]}"; do
+		key="${token%%:*}"
+		state="${token#*:}"
+		if ((key <= 0)); then
+			pm_fail "$(pm_unknown_item_message "$key")"
+			return 1
+		fi
+		if ! pc_enum_members_contains "$PC_VALID_ITEM_STATES" "$state"; then
+			pm_fail "$PM_REJECTION_PREFIX item $key state $(pc_repr str "$state") is not one of $PC_VALID_ITEM_STATES."
+			return 1
+		fi
+		if [[ $state == "$PM_PINNED_STATE" ]]; then
+			in_flight="$in_flight $key"
+		fi
+	done
+	if [[ -n $in_flight ]]; then
+		pm_fail "$PM_REJECTION_PREFIX close requires no item in flight; still in flight: $(pm_in_flight_list "$in_flight")."
+		return 1
+	fi
+	PM_RESULT='{"close_permitted":true}'
+	return 0
+}
+
+pm_build_close_entry() {
+	# Build the single run-scoped mutations[] record for an accepted close.
+	#
+	# Args: $1 = the generation, stamped unchanged, $2 = the `at` timestamp
+	# string. Returns 0 with PM_RESULT holding the record, 1 with PM_ERROR when
+	# the generation is negative.
+	local generation="$1" at="$2"
+	PM_RESULT=""
+	PM_ERROR=""
+	if ((generation < 0)); then
+		pm_fail "$(pm_entry_contract_message recolor_generation "$generation" close)"
+		return 1
+	fi
+	PM_RESULT="{\"op\":\"close\",\"item_key\":null,\"at\":$(pm_json_string "$at"),\"prior_state\":null,\"new_state\":null,\"disposition\":null,\"recolor_generation\":$generation}"
+	return 0
+}
+
+pm_build_requeue_entry() {
+	# Build the single mutations[] record for a drift-induced requeue.
+	#
+	# Args: $1 = item key, $2 = the generation before the requeue (stamps
+	# g + 1), $3 = the `at` timestamp string. Returns 0 with PM_RESULT holding
+	# the record, 1 with PM_ERROR holding the reference contract message.
+	local item_key="$1" generation="$2" at="$3" stamped
+	PM_RESULT=""
+	PM_ERROR=""
+	stamped=$((generation + 1))
+	if ((stamped < 0)); then
+		pm_fail "$(pm_entry_contract_message recolor_generation "$stamped" requeue)"
+		return 1
+	fi
+	if ((item_key <= 0)); then
+		pm_fail "$(pm_entry_contract_message item_key "$item_key" requeue)"
+		return 1
+	fi
+	PM_RESULT="{\"op\":\"requeue\",\"item_key\":$item_key,\"at\":$(pm_json_string "$at"),\"prior_state\":\"$PM_PINNED_STATE\",\"new_state\":\"blocked\",\"disposition\":null,\"recolor_generation\":$stamped}"
+	return 0
+}